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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe, non-destructive operation. The description adds that the search is scoped to capabilities for the current OAuth token, which is useful context. However, it doesn't describe pagination behavior for results, whether the search is full-text or exact match, or how detail='schema' affects the output structure. With the annotations covering the safety profile, a 3 is appropriate.

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 description is two sentences: first states purpose, second gives usage guidelines. Every sentence earns its place with no redundancy. It could be improved by front-loading the most critical info (perhaps moving the sibling tool reference earlier), but it's efficient and clear.

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?

Given the tool has an output schema and annotations providing safety profile, the description adequately covers purpose and usage guidance. The 3 parameters have inline constraints in the schema, and the description hints at their purpose (query for capability names, detail for schema retrieval). The mention of 'ask_podmule' as a fallback compensates for potential ambiguity. A slight gap is that it doesn't clarify if 'search' is prefix-based, fuzzy, or exact, but this is acceptable given the clear usage guidance.

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 0%, so the description must compensate for parameter meaning. The description itself only indirectly references parameters (the need for a 'capability name' implies 'query'), but the context signals note 0% coverage. However, the output schema exists (not shown here) which may clarify parameter effects, and the description's brief guidance helps the agent understand the tool's core parameter (query for capability names). The schema's parameters (limit, query, detail) have inline constraints (max/min, enum) but no textual descriptions, so the description's lack of explicit param talk is a gap, but acceptable given the concise format.

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 uses a specific verb 'search' and resource 'available PodMule capabilities for this OAuth token', clearly stating what the tool does. It acknowledges the sibling tool 'execute' by mentioning it needs the exact capability name, which helps distinguish its purpose.

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?

The description explicitly states when to use this tool ('when you need the exact capability name or schema before calling execute') and provides guidance for ambiguous domains ('call ask_podmule first'). It clearly distinguishes between its two sibling tools and gives conditional usage rules.

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