shows_without_new_episodes

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

With no annotations, the description carries the full disclosure burden and does reveal real behavioral detail: it pages /me/shows and then fetches the latest episode per show, and it states defaults of 30 days and 50 lookups. However, it does not disclose the cost implications of performing up to 50+ per-show API lookups, rate-limit exposure, or how shows with no episodes at all are handled.

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?

Two tight sentences with zero waste: the first front-loads the purpose and mechanism, and the second states defaults. The parenthetical "which pods went quiet?" is high-signal framing that earns its place, and nothing is repeated from the schema.

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 description adequately covers what the tool does and its defaults, and the response_format parameter partially fills the output-shape gap since no output schema exists. But with no annotations and no output schema, it should also convey the multi-call cost profile and result-sorting behavior, and it omits any direction to inverse siblings, leaving an agent under-informed about operational impact.

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 100%, with every parameter already documented including defaults, bounds, and semantics (e.g., max_shows as "request budget," response_format enum values). The description adds only a restatement of two defaults (30 days, 50 lookups), which is marginal value at the baseline level.

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 specific verb and resource: "Find saved shows with no episode released inside the lookback window," with the user-facing framing "which pods went quiet?" making the intent unmistakable. It also distinguishes itself from the inverse sibling show_new_episodes by describing the quiet-podcast query rather than the new-release query.

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 "which pods went quiet?" phrasing strongly implies the use case (identifying shows that have gone silent), and the defaults give a sense of the typical invocation. However, there is no explicit when-to-use versus when-not-to-use guidance against heavily overlapping siblings like show_new_episodes, get_newly_released_episodes, and stale_saved_shows_plan, leaving routing to inference.

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