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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, not open-world), and the description adds substantial context beyond them: the 50-row cap, the presence of a total match count, what in_latest_scan=false means, and the important caveat that verdict_since can span unmeasured weeks so freshness should be judged from last_checked_at plus in_latest_scan. This is exactly the kind of non-obvious behavior an agent needs and cannot get from the schema.

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 core purpose, usage hint, and parameter behavior are front-loaded and each sentence is informative. The final paragraph on verdict_since versus last_checked_at is dense and repetitive, but it prevents a genuine misinterpretation, so the length is mostly 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?

With no output schema, the description supplies the return contract itself (rows with latest verdict, total match count, freshness fields) and explains the ambiguous columns. It also clarifies the limit ceiling and the special meaning of in_latest_scan=false, leaving no gap an agent would need to fill by trial and error.

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 0%, so the description carries the full burden and does so: `query` is host or URL substring, `limit` is capped at 50, `network` is shown with two concrete format examples (eip155:8453, solana:5eyk...), and `sort=price` is explained as cheapest-first ordering. All four parameters gain meaning beyond their bare titles.

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: 'Search the catalogue by host or URL substring,' and states the return shape (up to `limit` endpoints with latest verdict plus total match count). It is clearly distinguishable from siblings like catalogue_stats or host_summary. It stops short of explicitly naming which sibling to use for exact-URL or aggregate lookups, so it lands at 4 rather than 5.

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?

'Use this first when you do not know the exact resource URL' gives a concrete when-to-use condition, and the network/sort options hint at refinement workflows. However, no alternative sibling is named for the known-URL case or for aggregate stats, so the routing guidance is clear but incomplete.

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