Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) already convey that this is a safe read-only operation. The description adds valuable context about what the response includes: full schemas/examples for exact tool names, and a top-level `connectors` array listing connected SaaS accounts. It also lists categories. These details go beyond the annotations by explaining the response format and how to interpret it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is fairly long but well-structured: it starts with the core purpose, gives examples, then outlines the flow and the connectors array, and finally lists categories. Each section earns its place without redundancy. It is more detailed than necessary for a simple tool, but the added length is justified by the discovery tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is rich in context: it needs to convey how to search, what categories exist, how the response looks (schemas, examples, connectors), and how to integrate with other tools. The description covers all of these. Since there is no output schema, the description effectively describes the response contents (including connectors array) and the expected usage pattern. An agent can confidently call this tool and interpret its results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented. The description enhances semantics by providing concrete query examples ('analyze a website', 'research competitors'), explaining that an exact tool name returns full schemas, and noting that category can be used for filtering. It clarifies the 'query' parameter's flexible usage (intent, category, or '*' list-all).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear purpose: 'Find the right ToolRouter tool for your task.' It specifies the resource (ToolRouter tools) and the action (locate/discover). It distinguishes itself from siblings by naming the workflow: use discover for schemas/listing, then use use_tool. It also lists categories and mentions the connectors array, making its scope unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit usage context: 'prefer route({ intent }) to pick and run a tool' and 'Use discover when you need schemas or a listing, then call use_tool(tool, skill, input).' It also explains how to leverage the connectors array to pick the right tool/account without asking. This directly addresses when to use discover vs its siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.