What tool descriptions do to agent success

Write tool names, descriptions, schemas and annotations that agents select correctly and that reviewers accept. The median open server lists 8 tools; the largest lists 173. First step: Name tools by action and object. Last step: Keep the tool count moderate.

Steps

1. Name tools by action and object.
2. Describe inputs, outputs and failure.
3. Add title and readOnlyHint or destructiveHint.
4. Keep the tool count moderate.

What the sources say

• Arcade's rescan (30 Sep 2026) scored average tool names at 79 and descriptions and input schemas at 57 each; seven in ten servers give no useful guidance when a call fails. Vendor research. (www.arcade.dev, dated 30 September 2026, read 4 November 2026)
• In the same rescan, tool annotations added nearly 11 points, and quality peaked at 16 to 31 tools per server. (www.arcade.dev, dated 30 September 2026, read 4 November 2026)
• Nearly 17,000 servers ship a destructive or irreversible tool, and only 14 percent declare safety annotations (Arcade, 30 Sep 2026). (www.arcade.dev, dated 30 September 2026, read 4 November 2026)
• Claude's directory requires a title and readOnlyHint or destructiveHint on every tool. (claude.com, read 4 November 2026)
• The 2025-11-25 revision added guidance on tool names (SEP-986) and input validation errors returned as tool execution errors so models can self-correct. (modelcontextprotocol.io, dated 25 November 2025, read 4 November 2026)

What public servers look like

Across 263 open servers the median tool count is 8, 31 list more than 40 tools, and the largest lists 173. Of 3,541 recorded tool names, 837 start with get, 253 start with list, 177 start with search, 97 start with create, 40 start with update, 33 start with delete.

How many tools a server lists is a separate question: the tool-count guide shows what the directory's servers do.