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

Annotations already declare a safe read (readOnlyHint true, destructiveHint false), and the description still adds substantive behavior beyond them: a 25-item cap, preservation of the requested order, exact-title matching ignoring case, a tie-break rule (most Apple ratings), and the existence of an unresolved bucket carrying a reason and candidate ids. This is the information an agent needs to interpret partial failures.

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 paragraphs: the first covers scope, output shape and sibling routing; the second covers matching rules and failure handling. The parenthetical field list ('audience, guest and sponsor signals, has_email') and the 25 limit read as dense but each sentence carries real information, with no 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?

There is no output schema, so the description has to carry the return shape, and it does: compact rows with named signals, order preserved, plus the unresolved structure with reasons and candidates. Combined with the batch limit and matching rules, an agent could construct correct calls and handle every outcome.

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 accepted input formats are already documented and the baseline is 3. The description contributes genuinely new semantics: sources can be mixed freely in one array, titles must match exactly apart from case, and ambiguous titles resolve to the highest-rated show. It stops short of stating what the candidate ids in unresolved look like.

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 (batch lookup of podcasts by id/URL/title) and explicitly positions itself against two siblings: it replaces one get_podcast per show and returns the same compact rows as search_podcasts. An agent can distinguish it from get_podcast, search_podcasts, and find_similar_podcasts without opening any schema.

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 (check or enrich a list of shows in bulk) and an explicit alternative with its condition (get_podcast for the few worth reading in depth). The only thing missing is a hard statement of when not to use it at all, but the routing guidance is otherwise complete.

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