# AX-SYS-11: Write tool descriptions for the model, not the human

> Tools and capabilities · foundational · AX-SYS-11

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

```json
{
  "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": "jane@acme.com", "limit": 10 }]
}
```

## Citations

1. [Anthropic — Writing Effective Tools for AI Agents](https://www.anthropic.com/engineering/writing-tools-for-agents) — Tool description quality is the primary determinant of correct tool selection; descriptions should state when to use the tool, what it returns, whether it has side effects, and include an example
2. [arxiv:2602.14878 — MCP Tool Descriptions Are Smelly](https://arxiv.org/abs/2602.14878) — Across 856 tools on 103 MCP servers, 97.1% of descriptions had at least one quality smell and 56% failed to state their purpose clearly; augmenting descriptions improved task success by a median of 5.85 percentage points
3. [MCP Specification 2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25) — MCP tools are defined with JSON Schema input parameters; description quality is the model's primary signal for deciding which tool to invoke

---
Source: Agent Experience Principles (axprinciples.com)