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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It explains what the tool returns (matching endpoints with method, path, summary, parameters, example) and the presence of a 'coverage' field for region-limited APIs. It does not explicitly state that it is read-only, but as a search tool it is inherently non-destructive. The description adds useful context beyond the schema, such as the region filter behavior ('Returns region-specific + global APIs; excludes APIs limited to other regions'), which enhances transparency. Missing explicit read-only statement is a minor gap but not a contradiction.

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 concise and information-dense, consisting of two sentences that cover the scope, result structure, usage guidance, and a key behavioral note. Every sentence adds value, and it is front-loaded with the most important information. There is no redundancy or fluff.

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 has 6 parameters, 1 required, and no output schema, so the description must convey the return value and usage context. It does explain what is returned and mentions the 'coverage' field and region filter. It does not explicitly mention pagination or the limit parameter, but since the schema documents limit with its default and maximum, that gap is acceptable. The description is complete enough for an agent to use effectively in conjunction with the sibling tools.

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?

The schema has 100% coverage for all 6 parameters, so the baseline is 3. However, the description adds significant meaning beyond the schema: it explains that the query matches 'operationId, summary, description, path, API name, tags; synonyms expanded,' which is not in the schema. It also elaborates on the region filter's behavior regarding global versus region-specific APIs. These additions give deeper semantics for key parameters, justifying a score above baseline.

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 clearly states the tool's purpose: 'Search across 484 endpoints in 59 APIs...' and specifies it returns matching endpoints with method, path, summary, parameters, and an example. It explicitly distinguishes itself from siblings by stating 'Use this to discover available API endpoints before calling execute_api.' This provides a specific verb (search) and resource (endpoints across APIs), and a clear distinction from the sibling tools.

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 explicitly says when to use it: 'Use this to discover available API endpoints before calling execute_api.' It also gives usage guidance for the region filter: 'Results carry a "coverage" field... use the "region" filter to narrow.' This is direct and clear about the context of use, fulfilling the dimension completely.

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