swarm-zap/skills/llm-tool-best-practices/hints/anthropic.md

MODEL_HINTS.md — Anthropic/Claude Tool Best Practices

Active model family: Anthropic (Claude)

When writing or evaluating skills/tools for this session, apply these rules:

Schema

• Use input_schema (not parameters) for tool definitions.
• Add strict: true for production tools — guarantees schema conformance via structured outputs.
• Use input_examples array for tools with complex inputs, nested objects, or format-sensitive params.

Descriptions

• Write 3–4+ sentences per tool: what it does, when to use/not use it, what each param means, what it returns, caveats.
• This is the highest-leverage factor in Claude's tool selection accuracy.

Model selection

• Use Claude Opus for complex/multi-tool tasks or ambiguous queries.
• Use Claude Haiku for simple well-defined tools only — it may infer missing params.

Tool design

• Consolidate related operations into fewer tools (e.g. one github_pr tool with action param vs three separate tools).
• Use service_resource_verb namespacing: github_issues_search, slack_channel_send.
• Return only high-signal fields. Prefer semantic names/slugs over raw UUIDs.
• Bound response size. Truncation messages should be actionable (tell Claude what to do next).
• For errors: plain-language messages, not stack traces.

Safety

• Least privilege on all tool permissions.
• Guard destructive/irreversible actions with confirmation or human-in-the-loop.
• Validate all tool inputs before acting.