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?

Adds substantial behavioral context beyond the annotations: reads run directly, the MRTR preview-and-affirm path for update_episode, legacy clients staying read-only, and dangerous writes being blocked. This explains the safety model and execution semantics meaningfully. No contradiction — readOnlyHint=false (writes possible) and destructiveHint=false (no destructive ops, aligning with 'dangerous writes always blocked') are both consistent with the text.

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?

Three dense sentences with the core purpose front-loaded ('Execute one OAuth-visible PodMule capability') and every sentence adding value — read behavior, pilot write path, dangerous-write policy, sibling routing. No filler, but the prose is jargon-heavy (MRTR, allowlisted, OAuth-visible) which slightly burdens comprehension per sentence.

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?

The presence of an output schema relieves it of describing return values, and it robustly covers the safety/write model and sibling routing. Yet the central gap remains: the actual capability set is never enumerated and input structure is left to the search tool. For a generic dispatch tool with a nested-object input and no enums, an agent still needs significant external discovery before calling it safely, so completeness is adequate but not full.

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 0% schema description coverage, the description must compensate for the 2 parameters but does so only indirectly. 'name' is hinted at via the update_episode pilot example and 'capability,' and 'search for exact schemas' points the agent to discover inputs elsewhere. It never explicitly defines what 'input' should contain or lists valid name values, leaving the agent reliant on external tooling rather than the definition itself.

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 verb ('Execute') and a resource ('one OAuth-visible PodMule capability'), moving beyond a tautology. However, the purpose is vague — the set of available capabilities is never enumerated, and 'name' has no enums or schema guidance. It does partially differentiate from siblings by routing ask_podmule to ambiguity and search to schemas, but the core scope remains undefined for an agent trying to decide what it can actually invoke.

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 gives explicit routing conditions: 'Use ask_podmule for ambiguous requests and search for exact schemas' names both alternatives and their triggers, and 'Dangerous writes are always blocked — do those in the PodMule app' states a clear when-not. The MRTR-pilot condition adds a client-dependent caveat. Only minor gap: it never states an explicit 'use execute when you have a concrete, allowlisted capability name' condition, though that is strongly implied.

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.