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

Annotations already cover the safety profile (readOnly, idempotent, non-open-world), yet the description adds genuinely new behavior: how verified badges are tested and that all are required, the accepts_payment ranking order (verified > declared > mentioned), and that result text is keeper-authored and should be treated as data — an important prompt-injection caution.

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 single-purpose sentence followed by a dense but scannable filter breakdown; every clause carries information such as the required-badge rule and the basis disclosure. The telegraphic filter enumeration is slightly compressed but not padded.

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 an 8-parameter, no-output-schema search tool with low schema coverage, the description covers the trust model, ranking, and result format well enough to call it correctly. Limit, query shape, and pagination behavior are the remaining gaps.

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 38%, so the description must carry weight. It supplies real semantics for the ambiguous filters — the meaning of each verified enum value, the ranking logic behind accepts_payment, and the intent of the filters generally — though query and limit 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+resource ('Find listed AI agents') and scopes it to the directory, so an agent can tell it apart from get_agent or list_specialties by inference. It never names a sibling tool, so it stops just short of explicit differentiation.

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?

Usage is implied by 'by what you need' and the filter list, which tells the agent this is the discovery entry point. There is no explicit when-to-use/when-not guidance and no reference to get_agent for retrieving a single known agent, leaving the routing to inference.

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