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

Annotations only declare readOnlyHint=true, but the description discloses far richer behavior: the 2+ appearance floor in directory mode, the exact press-tour shape in trends mode (distinct podcasts, 5+ minutes speaking time, mononymous exclusions, 2x spike over baseline), and the one-off guest inclusion when podcast_slug is used. This goes well beyond the structured 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?

The description is longer than average but information-dense, front-loaded with the core purpose and then structured as two clear mode bullets. Subsequent sentences explain parameter interactions and downstream tool usage. Every sentence adds value, though the trends bullet is slightly verbose and could be trimmed without losing essential criteria.

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 complex, multi-mode tool with two enums, four optional filters, and no output schema, the description covers all essential behavior: default mode, mode-specific thresholds, parameter combinations (podcast_slug switching to a show roster, topic_slug narrowing), and the read-only nature. The only omitted specifics, like podcast_slug being ignored in trends mode, are already present in the schema parameter descriptions.

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%, so the baseline is 3. The description adds meaningful context for mode, podcast_slug, and topic_slug, including how they interact and what changes in each mode. It also explains the intent behind output_format's markdown vs json distinction. It does not repeat trivial details for limit/cursor, which is acceptable given full schema coverage.

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 'Browse podcast guests across the catalog' — a specific verb and resource — and immediately distinguishes two modes, directory and trends. It clearly differentiates this from sibling tools like particle_podcast_get_guest (which focuses on a single guest) and podcast list tools for episodes/clips by centering on guests across the catalog or one show.

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 explicit guidance on when to use each mode: directory for lifetime rankings, trends for cross-show press tours with defined criteria. It also advises feeding guest slugs into particle_podcast_get_guest or particle_person_get, showing downstream routing. It does not explicitly contrast with all sibling list tools, but the mode selection and parameter constraints are clear enough.

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