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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), and the description adds substantial behavior beyond them: ranking order (more matched words first, then name), a cutoff rule dropping offerings matching under half the best match, treatment of country/language words in scoring, and the assurance that payment/ownership play no role. That is exactly the non-obvious ranking and filtering behavior an agent cannot get from structured fields.

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 trigger condition, then behavior, then the follow-up pointer — good ordering. A few clauses (the 'no scores and no paid positions' assurance) are trust-building rather than operational, so it runs slightly long, but every sentence is readable and mostly earns its place.

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?

With no output schema, the description still describes the return reasonably ('returns matching offerings with the terms they matched') and routes to get_offering for full records. Missing details are the limit default and whether results are paginated or how many are returned by default.

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 only 33%, so the description should carry more weight; it adds real semantics for query (country/language words are matched but not weighted, plain-language phrasing) but says nothing about limit (default value, effect on results) or schema_version. The query guidance is valuable, the remaining parameters are left entirely to the sparse 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 — 'Plain-language search over the Agent Company Index' — and names the follow-up tool get_offering. It does not, however, distinguish itself from the sibling discover_offerings, leaving the agent to infer which search is appropriate.

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 explicit triggering context ('Use when a user is looking for a B2B software product, service provider or agency') with two concrete example queries, which is strong. It stops short of an exclusion rule naming when to prefer discover_offerings or evaluate_situation instead.

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