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

With only a readOnlyHint annotation, the description carries the behavioral disclosure burden and exceeds it: it explains segment matching semantics, one-row-per-operation deduplication, spec splitting across tags, the `apis` list field, `max_providers` cap and truncation flag (`meta.query.truncated`), plus detailed pricing and estimate guidance. This is far beyond what annotations provide.

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 front-loads the purpose immediately, then delivers dense, high-value behavioral details with zero fluff. Every sentence adds essential information (matching semantics, deduplication, truncation, pricing), making the length justified.

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?

Given the tool's complexity (7 params, no output schema), the description covers query semantics, filtering, deduplication, truncation, and pricing. It leaves the exact response shape (operation fields list) unspecified, but it does mention `apis` and `meta.query.truncated`, giving enough for an agent to interpret results. A brief output-structure sentence would make it fully complete.

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 57%, and the description compensates well for the undocumented parameters: it explains `method` (not described in schema), reinforces `q` with segment semantics, and adds context to `deprecated` and `max_providers`. `page` and `limit` remain unexplained, but they are standard pagination parameters and the description covers the most important ones.

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 states a specific verb and resource: catalog-wide operation search matching path segments. It clearly distinguishes itself from tag-based searches ('tags are what a company says about itself, a path is what its API accepts') and implies it answers questions no other sibling tool could ('had no answer before this').

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 clear context on when to use the tool: to find which providers expose a specific API path, narrowable by method and deprecation status. It implies a contrast with tag-based search, but does not explicitly name sibling tools or state when not to use this tool (e.g., 'for per-provider operations use get_provider_operations').

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