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

Annotations only declare readOnlyHint/openWorldHint, so the description carries the behavioral burden and does so well: it discloses that all=false is the default, that uncovered capabilities are 'a real answer rather than a gap', and full pricing behavior ($0.005/request plus $0.0002/record, volume discount past 100, $0.50 cap, pay-as-you-go, included in Understanding and Influence).

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-loads the highest-value content ('START HERE', model size) and every sentence is functional, though the pricing clause is a dense run-on and reads slightly promotional ('Free.'). Still well under the size where it would obscure the primary purpose.

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 read-only 6-param discovery tool with no output schema, the description covers purpose, default behavior, cost model, and even the shape of the results (capabilities with provider-coverage counts). Nothing an agent needs to invoke it correctly 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 100%, so baseline is 3, but the description adds genuine semantics beyond the schema for `all` — explaining what the flag changes in the result set and why the zero-coverage rows exist. Other parameters (q, page, limit, industry, context) are left to the schema.

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?

States a specific verb and resource ('find capabilities', the business-capability model of 333 capabilities across 28 industries) plus scope ('with how many catalog providers reach each one'). The 'START HERE for what can a business do with these APIs' framing distinguishes it from the many other find_* tools an agent could pick.

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?

Gives clear entry-point guidance ('START HERE') and the key default-vs-alternative condition: defaults to capabilities the catalog actually reaches, pass all=true for the full model. It also advises estimating first at /api/v1/prices/estimate before calling. It stops short of naming an explicit sibling alternative (e.g. find_industries or get_capability) for narrower lookups.

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