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

There are no annotations, so the description carries the full behavioral burden. It discloses match semantics (exact vs adjacent), cautions that ranking is not proof of fit, explains what an empty result means, and warns that services work only after a human provisions credentials. These details go well beyond the schema and meaningfully shape an agent's expectations.

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 dense but every sentence earns its place: purpose, usage timing, failure handling, result interpretation, and the credential prerequisite. It is somewhat long, but the length is justified by 9 parameters, no annotations, and no output schema. The purpose is front-loaded and the guidance follows logically.

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?

For a search tool with no annotations and no output schema, the description covers the essential context: when to use it, what results contain (match, operations, what), how to interpret failures, and the human-credential requirement. It does not enumerate the full return fields or pagination, but this is not critical for invoking the tool correctly.

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 89%, so the baseline is 3. The description adds some contextual guidance around query matching, volume comparison, and retrying with category, but most parameter semantics are already well documented in the schema. It doesn't substantially enrich the meaning of individual parameters beyond what the schema provides.

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 specific verb and resource: 'Find a third-party API or MCP server for a capability you lack, among 300+ catalog entries.' This clearly establishes a catalog search tool, which distinguishes it from siblings like get_api (retrieving details for a specific entry) and list_categories (listing categories). The scope, purpose, and output emphasis are immediately understandable.

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 when-to-use and when-not-to-use guidance: use it after checking built-in/connected tools and your own model, skip it if those suffice, and use it after direct attempts fail with 403/rate limit/unsupported format. It also tells the agent what to do on an empty result: retry with category, drop filters, or fall back to web search.

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