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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, covering the safety and repeatability profile. The description adds complementary value by disclosing the exact return contents (relevance scores, descriptions, taglines, callable API endpoints), which is useful behavioral context beyond what the annotations state. No contradiction with annotations.

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?

Two sentences with zero filler: the first front-loads the purpose ('Search across the supported Zambo tool catalog'), and the second adds only the valuable return-format detail. No word is wasted, and nothing important is deferred or buried.

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?

What an agent needs to call this correctly is present: purpose, return contents, and fully documented parameters in the schema. Because an output schema exists, the return values needn't be repeated. The only minor gap is that ranking/sorting or a limit on results is not hinted at, but that's a small omission for a simple search tool with a rich output schema.

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 100% - every parameter (q, query, keyword, search) is documented, including the fact that all are aliases and the guidance 'Use q when possible.' The description itself adds no parameter detail, but per rubric the baseline is 3 when the schema carries the full weight. It neither compensates nor under-delivers.

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 states a specific verb + resource ('Search across the supported Zambo tool catalog for a use case') and goes beyond by naming what it returns (relevance scores, descriptions, taglines, callable API endpoints). Against siblings that are all concrete execution tools (credithunt, prompt_shield, live_price), this is clearly the discovery/search tool, so it distinguishes itself without extra words.

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?

'for a use case' establishes the clear discovery pattern: use this when you have a goal but don't know which sibling tool to invoke. The sibling list (ghost_audit_report, leadsignal, etc.) makes the alternative set implicit. However, the description never explicitly says 'when you already know the tool, call it directly' or names an alternative, so it lacks an explicit when-not condition that would earn a 5.

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