Tell the index a feed has new content

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

Annotations already provide idempotentHint and openWorldHint, but the description adds concrete behavioral details: safe to call more than once, needs no API key, works on unconfigured installs, and will not add a feed. It goes beyond the annotations without contradicting them. It doesn't mention return values or rate limits, but those are less critical for a one-parameter ping.

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?

Four focused sentences: action, when to use, safety/no-API-key constraints, and the explicit alternative. Every sentence earns its place, and the core action is front-loaded. No redundancy or filler.

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 simple tool with one parameter, no output schema, and supportive annotations, the description fully covers what an agent needs: purpose, trigger timing, idempotency, authentication requirements, and the edge case of non-indexed feeds. Nothing essential is missing.

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% and the show parameter is already well described ('feed id or its RSS feed URL', 'must already be in the index'). The description reinforces the 'already in index' constraint but adds no new format or syntax details, so the baseline of 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?

States a specific verb ('Ping') and resource ('Podcast Index') with the purpose ('say a feed has changed'), and explicitly distinguishes itself from submit_feed. The title also communicates the exact use case, so an agent can tell this tool apart from siblings.

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?

Provides an explicit trigger condition ('Use this straight after publishing an episode'), notes the fallback behavior ('the index will find it on its own eventually'), and names the alternative for a different scenario ('use submit_feed for that'). No inference is required.

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