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

Annotations only declare a safe read; the description goes far beyond by decoding the status taxonomy (verified/deprecated/other), explaining that sandbox verification does not prove production behaviour, and mandating a user warning when status is not 'verified'. It also predicts error shapes (isError with available_capabilities, did_you_mean, removed_in) and the _mcp_size_note truncation hint — behavior an agent could not infer from annotations.

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?

Front-loaded with the core action and its result, then organized as a field-by-field key, which is scannable despite its length. It is longer than typical, but nearly every line is a disambiguation rule for a returned field an agent must interpret; only the trailing error-handling sentence overlaps slightly with the Returns section.

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?

No output schema exists, so the description carries the full burden of explaining the response — and it does, covering status, verification, open_questions, environments, auth blocks, parameters vs input_schema, success_condition, and error cases. For a read-only lookup tool with three simple params, nothing an agent needs to call or interpret it is missing.

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 coverage is already 100%, so baseline is 3; the description earns extra by explaining what variant actually does — filtering oneOf/union branches by discriminator value, leaving unmatched unions whole, and surfacing the result under 'variants'. It also clarifies that a path parameter fills {name} in endpoint.url. The provider/capability params get no added syntax guidance beyond the schema examples.

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 first sentence states a specific verb and resource — 'Returns the full spec payload for a provider + capability' — plus what is inside (canonical_example.ts source). An agent knows exactly what it gets and can distinguish it from search_specs (discovery) and list_providers (enumeration).

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?

It gives explicit timing — 'before writing API calls' — and names the prerequisites: 'Use search_specs or list_providers first to discover available providers and capabilities.' It also states what to do on failure (pick from available_capabilities, use did_you_mean), which routes the agent rather than leaving it to guess.

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