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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description still adds useful context: it discloses the required 'Cotlet API key with access to this app' auth need and characterizes what the read returns (full show notes, media file info). No rate-limit or pagination notes, but this is a single-resource fetch.

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 first two sentences largely repeat the same field list (title, description, status, release date, season, episode number, type, rating, author, media file), which is redundant. Leading with a bare field fragment instead of the action also hurts front-loading, though the guidance sentence is well-placed at the end.

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?

With no output schema, the description usefully enumerates the returned fields, which is appropriate. Auth requirements and the pre-update workflow are covered. Adequate for a single-parameter read tool, lacking only return-shape details like tagging format.

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 100% and the schema already documents the sole parameter, including its provenance ('Episode ID from list_episodes'). The description adds no syntax or format detail beyond the schema, so baseline 3 is correct.

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 second sentence states a specific verb and resource: 'Returns one episode with its full show notes...' and enumerates the returned fields. It also implies differentiation from update_episode. However, the opening fragment ('Title, description (show notes), status...') reads like a raw field dump rather than a purpose statement, making the lead-in awkward.

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?

Gives an explicit when-to-use rule: 'Use it before update_episode so your agent edits the current text and does not overwrite it.' This names a concrete sibling and the workflow condition that selects it. No when-not-to-use cases or relationship to list_episodes beyond the schema's mention.

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