Check whether a feed is healthy

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

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds meaningful behavioral context beyond those: it relies on crawl history and reports specific diagnostic signals such as failed fetches, parse errors, last HTTP status, last successful read, and dead/duplicate status. This gives the agent a concrete model of what the call will reveal without contradicting the annotations.

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 sentences with no filler. The first sentence states what it does; the second removes a common assumption about ownership; the third gives a concrete use case. The most important information is front-loaded and 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?

For a single-parameter diagnostic tool, the description is complete: it identifies the input flexibility, the diagnostic evidence returned, and a motivating scenario. There is no output schema, but the description enumerates the key result categories, so an agent can understand what to expect. Minor gaps like not-found or invalid-input behavior are not critical for this tool.

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?

The input schema covers 100% of the single parameter and already states that 'show' can be a feed id, RSS URL, podcast GUID, Apple Podcasts URL, or iTunes id, with auto-detection. The description adds little parameter-specific detail because the schema is already rich, so the baseline 3 is appropriate.

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 opens with a specific verb, 'Diagnose', and names the exact resource, a podcast feed via the Podcast Index crawl history. It enumerates concrete symptoms (failed fetches, parse errors, HTTP status, last successful read, dead/duplicate) that distinguish this from generic feed lookups, and the wording clearly separates it from sibling tools like get_podcast or status.

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 a clear trigger: run it before blaming a host for a drop in downloads. It also tells the agent that the tool works on any feed in the index, removing an ownership prerequisite. However, it does not name alternatives or say when not to use it, so some routing judgment is still left to the agent.

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