--- title: "What tool descriptions do to agent success | Agent MCP Directory" description: "What tool descriptions do to agent success. Write tool names, descriptions, schemas and annotations that agents select correctly and that reviewers accept." canonical: https://agentmcpdirectory.com/guides/tool-descriptions-and-agent-success site: "Agent MCP Directory" last_updated: 2026-11-04 section: "Guides" --- # What tool descriptions do to agent success | Agent MCP Directory > What tool descriptions do to agent success. Write tool names, descriptions, schemas and annotations that agents select correctly and that reviewers accept. Source: https://agentmcpdirectory.com/guides/tool-descriptions-and-agent-success Site: Agent MCP Directory Last reviewed: 2026-11-04 # 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](https://www.arcade.dev/blog/toolbench-rescan-90000-mcp-servers), 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](https://www.arcade.dev/blog/toolbench-rescan-90000-mcp-servers), 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](https://www.arcade.dev/blog/toolbench-rescan-90000-mcp-servers), dated 30 September 2026, read 4 November 2026) - Claude's directory requires a title and readOnlyHint or destructiveHint on every tool. ([claude.com](https://claude.com/docs/connectors/building/submission), 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](https://modelcontextprotocol.io/specification/2025-11-25/changelog), 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. | Company | Tools | First names | | --- | --- | --- | | Courier | 173 | list_messages, get_message, get_message_content | | YouSpot | 171 | read_web_page, web_search, check_page_changes | | AthenaHQ | 113 | open_ai_access, check_public_ai_access, get_prompt_schedules | | Ciphyr | 112 | create_passport, whoami, invite_agent | | Okfindex | 107 | api_index, search_bundles, get_bundle | | Almxpp | 104 | validate_best_practices, find_extensions, ado_create_bug_from_test | | AgentBIT | 101 | agentbit_discover, agentbit_route, agentbit.address_eip55 | | DC Hub | 94 | execute_plan, claim_free_key, search | How many tools a server lists is a separate question: [the tool-count guide](https://agentmcpdirectory.com/guides/how-many-tools-an-mcp-server-should-list/) shows what the directory's servers do. ## Testing your own MCP server Ora scans an MCP server URL and runs 28 of its 132 public checks on it, with check sets that differ for a docs server and a product server. It is the check this directory recommends; it reads public URLs only and publishes no repeat-scan data. [The reasons, the limits and the alternatives](https://agentmcpdirectory.com/test-your-mcp-server/). Edition 4 November 2026 Method [How rows are verified](https://agentmcpdirectory.com/method/) Data [CSV and JSON](https://agentmcpdirectory.com/data/) Markdown [This page as markdown](https://agentmcpdirectory.com/guides/tool-descriptions-and-agent-success/index.md) ## Sources - [What tool descriptions do to agent success](https://www.arcade.dev/blog/toolbench-rescan-90000-mcp-servers), read 4 November 2026 - [claude.com/docs/connectors/building/submission](https://claude.com/docs/connectors/building/submission), read 4 November 2026 - [modelcontextprotocol.io/specification/2025-11-25/changelog](https://modelcontextprotocol.io/specification/2025-11-25/changelog), read 4 November 2026 Last reviewed 4 November 2026