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.