PodMule

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

The description states 'This tool never performs writes,' which is consistent with the annotations readOnlyHint=true and destructiveHint=false. It goes beyond the annotations by characterizing the nature of responses (concise, advisory) and noting it covers 'ambiguous action requests,' which implies it may return a route plan rather than executing actions. This adds value beyond the structured data without contradicting it.

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, tightly packed with useful information. It front-loads the core purpose and immediately follows with use cases and sibling differentiations. No filler or redundant phrasing; every sentence 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?

Given the tool's advisory nature, the description is sufficient: it clarifies read-only behavior, specifies use cases, and points to siblings. The presence of an output schema reduces the need to describe return values. However, it could briefly mention that the 'request' parameter should be a natural-language prompt or a specific format expectation, but the 'advisory' framing implies this. For a simple tool with clear annotations and output schema, this is nearly complete.

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?

With schema description coverage at 0%, the description must compensate for parameter meaning. While it doesn't detail each parameter, it conveys the overall intent: 'request' is the main prompt, 'response_format' determines output type (answer, route_plan, json), and 'context' provides optional scoping. The description's use of 'advisory route plan' implies that response_format='route_plan' is for guidance. However, it could be more explicit about how 'context' parameters are used, but the high-level purpose is clear.

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 clearly states the tool's purpose: to 'Ask PodMule for a concise read-only domain answer or an advisory route plan.' It lists specific use cases (quick questions, summaries, diagnostics, drafting, advisory prompts) and distinguishes itself from siblings by noting it does not perform writes, unlike execute. This is a specific verb+resource with clear 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?

Explicit guidance is provided: 'Use this for quick questions, summaries, diagnostics, drafting, "what should I do?" prompts, and ambiguous action requests.' It also gives exclusions: 'For exact capability contracts use search; for one selected action (read or write) use execute.' This clearly states when to use this tool versus alternatives and includes what not to use it for.

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

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

Annotations set readOnlyHint=false and destructiveHint=false, so the description correctly implies this tool can write. It adds significant behavioral context: capabilities flagged dangerous (deletes, sending real email) are blocked because there's no confirmation step, and the token must hold the capability's scope. This goes beyond annotations to explain constraints. Loses a point because it doesn't mention the error format or what happens when a capability fails (e.g., partial success), though the output schema may cover that.

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 three sentences, each serving a clear purpose: stating what it does, when to avoid it and alternatives, and safety/scope constraints. It is well-front-loaded. Loses one point because the first sentence is slightly verbose with the parenthetical list of examples, which could be trimmed without losing meaning.

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 2 parameters (one nested), 0% schema coverage, an output schema (not shown), and annotations that don't describe danger levels, the description covers purpose, routing, and safety well. However, it leaves the parameter 'input' completely undocumented, and the agent cannot know how to format arguments for different capabilities. The description gives enough context for selection but not enough for correct invocation, leaving a significant gap.

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 must compensate for both parameters. It only mentions 'name' implicitly as the capability to invoke, and 'input' is not described at all. The description gives no semantics for the input object (structure, allowed keys, required sub-fields). For a tool with nested objects and zero schema coverage, this is a major gap—the agent has no guidance on how to construct a valid input.

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 clearly states that 'execute' runs an OAuth-visible PodMule capability and lists examples of reads/writes (create/update, generate/apply images, schedule). It distinguishes from sibling tools by noting that broad questions should go to ask_podmule and exact schemas to search. However, the phrase 'Execute one OAuth-visible PodMule capability' is fuzzy for an agent unfamiliar with the domain, and the list of examples is broad, leaving some ambiguity about the exact resource being acted upon.

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 tells when to use this tool ('for capabilities your token has scope for') and when not to use it ('Do not use this for broad questions or ambiguous requests'). It provides clear routing guidance: use ask_podmule first for routing, search when exact schemas are needed, and dangerous operations should go to the PodMule app. This is excellent cross-referencing with sibling tools and usage boundaries.

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

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.