Write tool descriptions for the model, not the human

Tool descriptions are how the model decides what to call. Make them explicit and unambiguous, with input and output examples.

Why

Tool description quality directly determines correct tool selection. Anthropic's production guidance is clear: descriptions should state when to use the tool, what parameters it takes, what it returns, whether it has side effects, and include a worked example. A terse label like "search" is worse than useless: it tells the model nothing about when to call it or what to expect. One study of 856 tools across 103 MCP servers (arxiv:2602.14878) found that 97.1% of descriptions had at least one quality smell and 56% never stated their purpose clearly, and that augmenting those descriptions improved task success by a median of 5.85 percentage points. These descriptions are not UI copy — they are the model's decision substrate.

Do

State when to use it, the params, and a sample call. Bad: "search". Good: "search_orders: find a customer's orders by email or order ID; returns up to 50, newest first".

Don't

Reuse terse human UI labels.

Artifact

{
  "name": "search_orders",
  "description": "Use this to find a customer's orders by email or order ID. Returns up to 50, newest first. Does not modify anything.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "Email or order ID" },
      "limit": { "type": "integer", "default": 20, "maximum": 50 }
    },
    "required": ["query"]
  },
  "examples": [{ "query": "[email protected]", "limit": 10 }]
}