Write tool descriptions and parameter names as if onboarding a new hire

The model only knows what the tool definition tells it. Anthropic recommends writing descriptions the way you would explain the tool to a new teammate, making implicit context explicit.

A good definition covers:

• what the tool does and when to use it instead of a similar tool;
• what each parameter means, with units and formats;
• example usage and edge cases;
• what the tool returns and what errors look like.

Use unambiguous parameter names: user_id rather than user. Enforce a strict schema so bad arguments fail early.

The article notes that small refinements to tool descriptions produced large improvements, including a state-of-the-art result on the SWE-bench Verified coding benchmark.

{
  "name": "search_orders",
  "description": "Search this customer's orders, newest first, max 20. Use before get_order.",
  "input_schema": {
    "type": "object",
    "properties": {
      "status": { "type": "string", "enum": ["open", "shipped", "cancelled"] },
      "placed_after": { "type": "string", "description": "ISO 8601 date" }
    },
    "additionalProperties": false
  }
}