Write Tool Descriptions Like Claude Reads Them: Five Rules That Double Agent Routing Accuracy

Claude selects which tool to call based entirely on your JSON Schema description — write it like precise documentation with negative framing and you eliminate most routing bugs without touching your prompts.

Every agent's tool-calling loop runs the same model-side logic: Claude reads each tool's description field and decides whether to call it. If your descriptions are vague, Claude guesses wrong. If they're precise, routing works first time. Here are five rules that consistently close the gap.

Rule 1: Lead with what the tool does, not what it returns.

# Bad
"description": "Returns a list of user records"

# Good
"description": "Search the user database for accounts matching a name, email, or ID. Returns matching records."

The model routes on intent (what is this for?), not output (what does it give me?).

Rule 2: Name every constraint in the description — not just the type.

# Bad
"query": {"type": "string"}

# Good
"query": {
    "type": "string",
    "description": "A single search term. No boolean operators or wildcards. Example: 'alice@example.com'"
}

The type tells Claude what to send. The description tells Claude whether to send it at all.

Rule 3: Use negative framing to disambiguate similar tools.

When two tools overlap, add one line stating what NOT to use this tool for:

"Use this to look up a specific user by ID or email.
 Do NOT use for listing all users — call list_users for that."

Claude weighs exclusion text heavily when choosing between tools.

Rule 4: Include one example input in the description.

A single concrete example resolves ambiguity faster than three paragraphs of prose. Paste it at the end of the description field, not in a comment.

Rule 5: Set required vs optional correctly.

If a parameter is in required, Claude will attempt to fill it before calling. Parameters not in required get omitted unless explicitly needed. Mismatches here cause unnecessary retry loops.

Putting it together:

tools = [
    {
        "name": "get_user",
        "description": (
            "Look up a single user account by ID, email, or username. "
            "Returns the full user record including preferences and status. "
            "Use for lookups of a known specific user. "
            "Do NOT use for browsing or listing users — call list_users instead. "
            "Example: get_user(identifier='alice@example.com')"
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "identifier": {
                    "type": "string",
                    "description": "A user ID (integer as string), email address, or username. Do not pass a display name."
                }
            },
            "required": ["identifier"]
        }
    }
]

Apply these five rules to every tool your agent exposes. The payoff is fewer retries, fewer wrong-tool calls, and agents that handle edge-case routing without a prompt rewrite.

Sources: Tool use — Anthropic docs · Best practices for tool definitions — Anthropic prompt engineering