op3_top_countries

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

With no annotations, the description fully discloses behavioral traits: it counts raw records and aggregates client-side, uses a sample, defaults to recent data via window_days, and notes rate limits. This is comprehensive and confirms no destructive behavior.

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 efficient, with a clear first sentence stating the purpose, followed by essential context about limitations and defaults. Every sentence adds value, though the technical note about OP3's ordering could be slightly more integrated. Still, it avoids fluff.

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?

Given the complexity (7 parameters, no output schema in provided schema), the description explains how the tool works (client-side aggregation from raw records), what each result contains (download count and percent share), and important caveats (representative sample, rate limits). This is complete enough for an agent to understand the tool's behavior and output.

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?

All 7 parameters are described in the input schema (100% coverage), so baseline is 3. The description adds value by explaining the rationale behind defaults (e.g., window_days to keep sample recent, max_records for speed and rate limits) and the note about OP3's lack of native geography query, which clarifies the tool's design. This elevates it above baseline.

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 clearly states the verb ('Get') and the resource ('top listener countries (or regions) for a show'). It distinguishes itself from sibling tools by focusing on geographic aggregation, unlike op3_downloads_timeseries or op3_episode_downloads which handle time series or per-episode data.

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 explains when to use the tool (to get top countries/regions) and provides context on its limitations (representative sample, not exact). However, it does not explicitly advise against using it in cases where exact totals are needed or suggest alternatives among sibling tools.

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