stale_saved_shows_plan

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

With no annotations provided, the description carries the full behavioral burden and credibly discharges it: 'read-only by design, it never unfollows anything' is a strong safety disclosure for an agent deciding whether invocation is side-effect free, and the defaults (90 days, 50 show lookups) pin down runtime behavior. It does not, however, describe the plan's output shape or whether a run performs live network lookups, since no output schema exists to cover that.

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 dense sentences front-load the core purpose, then add the safety qualifier, the commit pairing, and the defaults in order of importance. No clause is wasted; the em-dash construction keeps the critical 'never unfollows' information adjacent to the main verb.

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 plan/commit workflow is complete for a tool whose four parameters are all optional and fully self-documented. The main gap is that, with no output schema, the description never says what the plan contains, and it doesn't differentiate itself from report-style siblings (shows_without_new_episodes, show_backlog_report) that also surface stale-show information.

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%, so the input schema already documents the meaning, bounds, and enum of all four parameters. The description's 'Defaults to 90 days, 50 show lookups' usefully restates the schema's per-parameter defaults in one place but adds no new semantic information beyond it, matching the high-coverage baseline of 3.

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?

States a specific verb and resource: 'Build a PLAN for pruning saved shows that have published nothing within the staleness threshold.' The read-only qualifier and the pairing with remove_saved_shows clearly separate it from the commit-style mutation tools in the sibling list, so an agent can tell it apart from remove_saved_shows and shows_without_new_episodes.

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 an explicit workflow: 'read-only by design, it never unfollows anything; pair with remove_saved_shows to commit' tells an agent to run this first for review and delegate the actual unfollowing to the named sibling. It stops short of a full 5 because it names no when-not-to-use conditions and doesn't route to analysis-only alternatives such as shows_without_new_episodes or show_backlog_report.

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