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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint:false, so the safety profile is established. The description adds valuable behavioral nuance beyond those annotations: it cautions that download share can be inflated by apps that re-request files, and it advises that listener share is the more honest metric. This helps the agent interpret results correctly rather than simply invoking the tool.

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 three sentences with no filler: it states output scope, gives a routing rule with rationale, and adds a column-interpretation caveat. Every sentence earns its place, and the most important information is front-loaded.

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 read-only query tool with a rich schema and strong annotations, the description is complete: it tells the agent what the tool returns, when to prefer it, how to interpret its columns, and how it differs from a close alternative. The lack of an output schema is compensated by the description already naming the key output dimensions.

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 input schema already documents all five parameters including defaults, bounds, and formats. The description reinforces the importance of start/end window semantics but does not add parameter-level information beyond what the schema provides, 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?

The description starts with a specific, concrete statement of what the tool returns: the podcast apps a show's audience uses, with unique listeners alongside downloads, over a user-selected window. It is clearly distinguishable from siblings like op3_global_app_share by emphasizing 'a show's audience' and from OP3's built-in app query by emphasizing flexible windowing.

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 explicitly tells the agent when to prefer this tool over OP3's built-in app query: whenever the window matters, because the built-in endpoint is locked to the last three calendar months. This is direct, actionable routing guidance that prevents incorrect tool selection.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds valuable interpretation of the key metric, downloadsPerListener, and warns that other download figures are inflated by re-requests. This goes beyond the annotations and helps the agent understand the result's meaning.

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 compact and front-loaded with the core purpose. The second sentence explains interpretation of the key metric without unnecessary filler. Every part adds value.

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?

With no output schema, the description helpfully explains the central output concept, downloadsPerListener. Parameter semantics are fully covered by the schema, and annotations cover safety. It could be more explicit about the full set of returned fields, but it is sufficient for an agent to select and invoke the tool effectively.

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 schema fully documents all four parameters. The description adds only general context like 'over any window' but does not provide additional parameter-level detail beyond what the schema already includes, meriting the baseline score.

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 states a specific, meaningful objective: compute unique listeners against downloads for a show over any window. It clearly differentiates from other endpoints by emphasizing 'how many people, not how many requests,' which distinguishes it from download-focused sibling tools.

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 implicitly tells the agent when to use this tool: when the true audience size matters and when other endpoints only provide request counts. It says 'every rolled-up endpoint cannot give you' this number, giving clear usage context, though it does not explicitly name alternative tools or exclusion criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so safety is covered. The description adds valuable behavioral context: the result is a relative index, not raw share, and a high raw percentage can still be an under-index. It does not describe output shape or sorting, but the core interpretation is clear.

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 front-loads the core definition and uses a single concrete example to make the index concept actionable. The sentence about turning app share into something actionable is slightly promotional, but it reinforces purpose without making the description bloated.

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?

With fully documented parameters, read-only annotations, and no output schema, the description supplies enough output semantics—app mix benchmarked against global mix with 100 as average—for an agent to invoke the tool and interpret results. It could be more explicit about the response being a per-app list, but the core intent is unambiguous.

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 each parameter already has a meaningful description, so the baseline of 3 applies. The tool description adds no parameter-level detail beyond what the schema provides; the min_share rationale is in the schema, not in the description.

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 identifies the resource (a show's app mix), the comparator (OP3's global mix), and the key output concept (an index where 100 means exactly average). It does not use an explicit verb like 'benchmark' or 'compare', and it does not name sibling alternatives, but the 'against OP3's global mix' phrasing distinguishes it from raw app-share tools.

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?

It provides a concrete use case: look for over-indexed apps to find where this audience is unusual and reachable. The Apple Podcasts example also explains why raw share is a misleading filter. It does not explicitly say when to prefer op3_app_share or op3_global_app_share instead, so exclusions are absent.

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

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

Annotations already declare this as a safe, read-only operation. The description adds useful behavioral context: the request accepts many shows at once and returns ranked comparison data across monthly downloads and weekly average. No contradictions with annotations are present.

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?

Three focused sentences, each earning its place: the first states the core function, the second explains batching efficiency, and the third gives concrete use cases. The key elements are front-loaded.

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 single parameter, the read-only annotations, and the clear purpose, the description provides enough context to select and invoke the tool. It does not detail the output format, but no output schema exists and the ranked comparison result is reasonably inferable from the description.

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?

The schema already provides 100% parameter coverage, including the accepted identifier formats, the 2-to-20 item limit, and the extra lookup cost for non-UUID identifiers. The description does not add meaning beyond what the schema states, so baseline 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?

The description states a specific verb ('compare'), a clear resource ('several shows side by side'), and concrete metrics ('monthly downloads and weekly average, ranked'). This clearly distinguishes it from single-show tools like op3_get_show or op3_show_downloads.

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?

It explains when this tool is appropriate: benchmarking a show against category peers or tracking multiple shows at once. It also notes that one request handles many shows, implying it should be preferred over repeated single-show calls, though it does not name specific alternatives.

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

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

With annotations already declaring readOnly, idempotent, and non-destructive behavior, the description adds valuable output behavior: all four dimensions are returned in a single call, avoiding the need for multiple requests. There is no contradiction with 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?

Three sentences, front-loaded with the core concept and with the dimensions enumerated efficiently. The final sentence adds selection context and is not wasteful, though slightly promotional.

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?

Since there is no output schema, the description does well to communicate that the call returns all four dimensions at once. However, it does not describe the result structure, ordering, or how the 'top' parameter applies per dimension, leaving some ambiguity for an agent with no output schema to rely on.

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?

The schema description coverage is 100%, so the parameter semantics are already documented structurally. The description adds no parameter-level details beyond what the schema provides, keeping this at the 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 what the tool does: it explains how a show is consumed across four named OP3 dimensions and notes that one call returns all four. It is specific about the resource and the shape of the result, though it does not explicitly name a sibling tool it should be distinguished from.

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?

It gives a useful selection cue: 'One call returns all four, which is what you want for a picture of the audience rather than a single ranked list.' This implies when to use it, but it does not name alternatives or provide explicit when-not-to-use guidance.

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

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

The description discloses a non-obvious behavioral detail: growth compares the two halves of the window rather than endpoints, with the weekly-seasonality rationale. This goes beyond the readOnly/idempotent annotations and helps an agent interpret the returned growth rate correctly.

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 compact sentences, with the core output front-loaded and a high-value rationale in the second. No repetitive or unnecessary wording.

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 description plus the fully-covered schema and read-only annotations is sufficient for an agent to invoke the tool. It names the returned data elements, though it does not describe the exact response shape or explicitly route between sibling tools.

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?

The schema already covers all parameters, but the description adds meaning to start/end by explaining that growth compares window halves. It also reinforces granularity semantics with the bucketing phrase, raising it above the 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 identifies the resource (a show's downloads and unique listeners) and the time-series nature, also mentioning growth rate and peak period. It lacks an explicit verb, but it is specific enough to distinguish it from aggregate sibling tools like op3_show_downloads.

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 implies use for time-series analysis of a show, and the growth explanation gives useful context, but it does not explicitly state when to prefer this over siblings or when not to use it. No alternative tools are named.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses key behavior: the comparison is age-normalized, the median is computed only from episodes at least as old as the horizon, and the tool returns a verdict. This prevents misinterpretation of raw download totals and explains why a young episode won't distort the median.

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?

Three sentences, each earning its place: purpose and output, why this tool matters, and how the median is constructed to avoid bias. It is front-loaded and contains 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?

For a read-only analytics tool with full schema coverage and no output schema, the description explains what is returned, how the comparison works, and why it is fair. An agent has enough context to select and invoke the tool correctly without needing more detail.

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?

The schema already documents all parameters at 100% coverage, so the baseline is 3. The description adds useful semantic context by explaining that only episodes at least as old as the horizon enter the median, which clarifies the role of horizon_days, and the notion of 'comparable episodes' gives meaning to compare_episodes. Other parameters like bots and identifier do not need additional explanation.

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 what the tool returns: cumulative downloads by day after publication, the median across comparable episodes, and a verdict. It describes the resource (an episode's curve relative to the show's own median), but it does not explicitly name or differentiate from sibling tools like op3_episode_downloads or op3_compare_shows.

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 a strong when-to-use signal: it is 'the only fair way to judge a recent episode' and explains why raw total downloads are misleading because older episodes have had more time to accumulate. It does not explicitly name alternative tools or state when not to use this tool.

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

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

Annotations already establish this as read-only, idempotent, and open-world. The description adds meaningful behavior beyond that: empty results are normal for small/new shows because OP3's daily rollup may not have covered them yet. This prevents the agent from misinterpreting an empty response as a failure. It also communicates the time-window structure of the returned data.

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 concise sentences: the first states the core function and return metrics, the second gives the primary use case and a valuable caveat about empty results. Every sentence earns its place with no repetition 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?

Given the schema fully documents parameters, annotations cover safety and idempotency, and the description explains the metric, use case, and empty-result semantics, nothing essential is missing. The lack of an output schema is mitigated because the description already says what is returned. It is complete for a read-only query tool of this complexity.

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 schema already documents both identifiers and limit fully. The description adds no new parameter-level detail, but it reinforces that the identifier refers to a show, which is consistent with the schema. Baseline 3 is appropriate because the schema carries the load and the description does not need to compensate.

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 states a specific resource (per-episode download counts) and precise metric (downloads in first 1, 3, 7, 30 days plus all-time). This clearly differentiates from show-level tools like op3_show_downloads and curve tools like op3_episode_curve, which would otherwise be plausible 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?

The description gives an explicit use case: 'Use it to compare how episodes performed at equal age.' This provides clear context for why an agent would select this tool. It does not explicitly name alternative tools or when not to use it, but the guidance is strong enough to route an agent correctly.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds valuable behavioral context beyond annotations by explaining that the symmetric similarity is near zero for a big/small episode pair and that the smaller side's share is the diagnostically meaningful number. This helps the agent interpret results and avoid misreading the metric.

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 sentences with no filler. The first sentence states the primary purpose; the second delivers essential interpretation guidance that prevents a predictable misinterpretation. Every part earns its place.

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 read-only tool with no output schema, the description explains the core result fields—shared listeners, symmetric similarity, and the smaller episode's audience share—and how to read them. It is slightly light on exact return structure, but the parameter schema covers inputs and annotations cover safety. Overall it is complete enough for confident invocation.

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 parameters (identifier, start, end, bots, top_episodes) are already well documented elsewhere. The description does not add parameter-level detail, but it does reinforce the meaning of top_episodes by referring to 'the show's busiest episodes'. This is adequate but not compensatory.

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 uses a specific verb ('reports') and resource ('each pair of a show's busiest episodes') and clearly distinguishes itself from sibling tools like op3_episode_downloads or op3_compare_shows by targeting episode-to-episode audience overlap within a single show. It is not a tautology and goes beyond the tool name.

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 implies when to use the tool—when you need audience overlap between a show's top episodes—but it never explicitly states alternatives or when not to use it. The interpretive note about interpreting the smaller side's share is useful, but selection guidance against sibling tools is absent.

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

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

The description adds meaningful behavior beyond the annotations: it reports downloads and listeners side by side to avoid misleading small-market conclusions, qualifies regions and metros by country, notes metro is US-centric and mostly empty elsewhere, and implies folded results through the top parameter. This directly shapes how an agent interprets the output.

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 compact and front-loaded: the purpose appears in the first sentence, granularity options in the second, and the country-qualification caveat earns its place. Every sentence adds information without repetition.

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 read-only analytics tool with rich annotations and full schema coverage, the description covers the key decision-relevant context: available geography levels, the unique-listeners pairing, metro's US limitation, and the country-qualification nuance. No critical gap remains for an agent deciding whether and how to call it.

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 schema already documents all six parameters thoroughly. The description reinforces the meaning of level and top through examples and caveats, but does not need to add further parameter detail.

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 states exactly what the tool does: reports downloads and unique listeners by geographic area, selectable at five granularity levels. It clearly distinguishes this from sibling analytics tools by focusing on geography rather than episodes, devices, or trends.

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 clear context on when the tool is appropriate: any geographic breakdown of a show's audience, with 'country is the usual answer' as practical guidance. It does not explicitly name alternative tools or when not to use it, but the geographic focus and level guidance are strong enough for an agent to route correctly.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond that: include_episodes is off by default due to potentially hundreds of episodes, and episode IDs obtained here are the basis for downstream episode tools. No contradiction with 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?

Three sentences, each earning its place: the main purpose, the optional behavior with rationale, and the downstream usage of returned IDs. It is front-loaded and free of 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 read-only lookup with three well-described parameters, the description is complete. It covers what data is returned, the optional episode expansion, and how the results connect to other tools. No output schema exists, but the listed return fields are sufficient for the agent.

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 parameters are already well documented. The description reinforces the purpose of include_episodes and the role of episode IDs but does not add significant semantic detail beyond what the schema already provides. Baseline 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?

The description clearly states the action ('Look up a show on OP3') and the resource, listing the returned fields (uuid, title, podcast guid, public stats page) and the optional episode list. It does not explicitly distinguish this tool from siblings like op3_resolve_show, but the core purpose is specific and understandable.

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 clear context: use this tool to look up a show and optionally retrieve episode IDs, and notes that these episode IDs are what episode-level tools filter on. It does not explicitly name alternatives or say when not to use it, but the context is enough for an agent to know when it is relevant.

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

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

Annotations already provide readOnlyHint, destructiveHint, and idempotentHint, so the description only needs to add context beyond safety traits. It adds the fixed trailing-thirty-day window, the global aggregation scope, and clarifies that results are not per-show—useful behavioral context beyond the 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?

Three sentences with no filler. The definition is front-loaded, the benchmark context is useful, and the device example earns its place by clarifying an optional parameter's real-world use.

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 read-only, idempotent benchmark query, the description plus annotations cover what the tool returns conceptually, its scope, its time window, and the available narrowing. It does not explicitly describe the response format, but the absence of an output schema and the simple market-share concept make this acceptable.

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?

The schema already describes both optional parameters fully, including an example device name and the source for device names. The description adds a small usability signal about narrowing to a device, but it does not meaningfully extend the schema's parameter documentation.

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 a specific function and resource: podcast app market share across every show OP3 measures over the last thirty days. It explicitly distinguishes this from any single show's numbers, which differentiates it from per-show app share 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?

It says this is the industry benchmark and useful for landscape-level questions, while noting it is not a single show's numbers, which implies per-show questions should use another tool. It also gives a concrete usage example for narrowing by device, though it doesn't name alternative sibling tools explicitly.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description's extra value comes from explaining the two output rates and the interpretative caveat that a show can score well on one rate and badly on the other. This adds useful behavioral context beyond annotations, though it does not cover edge cases such as empty periods or sampling details.

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 front-loaded with a clear definition and then, in a few sentences, explains both output metrics and an important caveat. Every sentence earns its place, though it is slightly more conceptual and wordy than the leanest possible definition.

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?

With no output schema, the description compensates by explicitly naming and defining both return rates, which is enough for an agent to interpret the result. Combined with schema-covered parameters and defaults, the tool can be invoked correctly; the only notable gap is the lack of explicit sibling differentiation.

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 schema already documents all five parameters and their defaults, which makes 3 the baseline. The description adds conceptual framing about earlier and later periods but does not add new parameter-level details, so it does not exceed 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 defines what the tool does: it computes cohort carry-over between two periods and returns two distinct rates, retentionRate and carryOverShare, with specific meanings. It is specific about the resource and metric, but it does not explicitly compare itself to sibling tools like op3_new_vs_returning or op3_episode_overlap, so it misses the top score.

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 clear context for when to use this tool by explaining what each rate answers: retentionRate indicates whether the show holds its audience, while carryOverShare indicates whether the show is growing or recycling. This is effective usage guidance, though it stops short of naming alternatives or stating when not to use the tool.

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

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

Beyond the readOnly/idempotent/destructive annotations, the description warns that scheduled background refreshes can dominate the pattern and that peaks partly reflect app defaults. This prevents a real misinterpretation and is valuable behavioral context.

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?

Three sentences front-load the key dimension (time buckets), then give a concrete use case and an essential caveat. Every sentence earns its place with no redundancy.

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 read-only analytics tool with fully documented parameters and no nested schema, the description covers what the data is, the timezone, the use case, and how to interpret it correctly. Nothing needed to invoke or understand the report 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%, so the schema already documents start, end, identifier, and bots. The description adds the UTC timezone context but otherwise does not need to repeat parameter meanings; a baseline 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?

The description clearly states the tool reports download timing aggregated by hour of day and day of week in UTC, which is a specific resource and dimensions. It distinguishes this report from sibling analytics tools by naming the exact grouping and the publication-slot use case.

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?

It explicitly says the report is useful for choosing a publication slot, and adds an important interpretation caveat about request timing versus listening behaviour. It does not name alternative tools or exclusion conditions, so it stops short of full routing guidance.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds useful behavioral context: results are newest first, titles are third-party text from the publisher's RSS feed, and the tool is positioned as a prerequisite before episode-level queries. No contradiction with 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 three sentences with no filler. It front-loads the core behavior, then gives the practical usage guidance and a relevant caveat about title source. Every sentence earns its place.

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 listing tool with rich annotations and a fully documented schema, the description is complete. It states what the output contains, the ordering, the usage purpose, and a data-quality caveat. No output schema exists, but the description sufficiently conveys the expected return shape.

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 parameters identifier, limit, and search are already thoroughly documented. The description adds context about the returned fields and the use case, but it does not add significant parameter-level meaning beyond what the schema already provides. Baseline 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?

The description states a specific verb ('List') and resource ('a show's episodes'), and specifies the returned fields: OP3 episode ids, titles, and publication dates, ordered newest first. This clearly differentiates it from sibling tools like op3_get_show, which focuses on show-level info rather than episode listing.

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 explicitly tells the agent when to use this tool: 'Use it to find the episode id for a specific episode before asking anything episode-level.' This gives clear context and a prerequisite, though it does not explicitly name alternatives or when-not-to-use conditions relative to sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: the baseline length affects results, the default is four times the window, and both baseline and window sizes are reported so the agent can judge reliability.

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?

Three compact sentences, each earning its place: the first defines the operation, the second states the use case, and the third flags an important behavioral nuance. The critical caveat about baseline length is front-loaded within the third sentence and clearly explained.

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 tool with no output schema, the description does well by stating that both sizes are reported. It explains the default baseline multiplier and its effect. It could be more explicit about what 'first-time' and 'returning' mean operationally, but the schema and description together provide sufficient context for correct invocation.

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?

The input schema has 100% description coverage and already explains identifier, start, end, bots, and baseline_multiplier. The description adds conceptual meaning about how the baseline comparison works and why baseline length matters, but it does not substantially extend parameter-level semantics beyond the schema.

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 states a specific verb ('Split') and resource ('a show's listeners in a window') and clearly differentiates the tool's purpose from siblings by focusing on first-time vs returning listeners. It also states the core question the tool answers, making its role distinct.

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 clear context for when to use this tool: when you want to know whether a show is reaching new listeners or serving the same audience. It does not explicitly name alternatives or exclusions, but the purpose framing provides enough guidance for an agent.

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

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

The description adds several non-obvious behaviors beyond the annotations: rows are ordered oldest first, there is no way to reverse ordering on this endpoint, the limit selects the earliest rows, and per-listener identifiers are removed from output. These are exactly the behavioral details an agent needs to interpret results correctly.

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 dense but every sentence earns its place: core purpose first, then routing guidance, then ordering/limit behavior, then privacy. It avoids repeating schema fields or annotation contents.

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 description covers the non-obvious decision-relevant context: when to prefer siblings, ordering limitations, limit behavior, and removal of listener identifiers. Since there is no output schema, the returned row fields are not enumerated, which is a small gap, but the description is otherwise sufficient for an agent to invoke and reason about the tool.

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 cross-parameter guidance: limit interacts with the oldest-first ordering, and start is the way to reach recent rows. This enriches the semantics of limit and start without restating the schema.

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 by stating the exact resource and result: raw download rows for a show with every filter OP3 offers. It also distinguishes this tool from the aggregating siblings by calling it the escape hatch for questions they do not cover, so an agent can tell it apart without opening schemas.

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 explicitly names the preferred alternatives (op3_show_downloads, op3_audience_summary, op3_geography, op3_app_share) and explains why raw rows should be avoided when possible: they are slow to fetch and expensive to reason over. It also gives concrete query strategy: because rows return oldest first, narrow the window with start rather than raising limit to see recent activity.

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

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

Beyond the read-only and idempotent annotations, the description discloses that results span every show unless filtered by URL, and that rows include user agents, byte ranges, and edge information. This adds meaningful behavioral context, though it does not address potential volume/cost implications of querying all shows.

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 compact and well-structured: it states what the tool returns, why that matters, and when to use a different tool. Every sentence earns its place and the key scope limitation is front-loaded.

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 no-output-schema tool, the description gives enough clarity about the kind of data returned and the default cross-show scope. It lacks explicit details about response shape beyond a few example fields, but the schema covers parameters and the description covers semantics sufficiently.

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 all five parameters are already documented in the input schema. The description adds little parameter-level detail beyond reaffirming that the URL filter is the scoping mechanism, which is already present in the schema.

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 that the tool returns raw request rows from OP3's redirect log, positioned as the lowest-level verification surface rather than an analytics tool. It explicitly contrasts this with show-level analytics tools, making its scope and purpose easy to distinguish 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?

It explicitly says to use the show tools instead when the question is about a specific show's performance, and frames this tool as a verification surface. This gives the agent clear routing guidance between raw log inspection and analytics queries.

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

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

Annotations already establish that this is read-only, idempotent, and non-destructive. The description adds important behavioral context: it returns podcast guids, not transcript text or download counts, and it covers all of OP3 with newest-first ordering. This prevents a common misinterpretation of what 'recent transcripts' means.

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 compact and front-loaded: what the tool returns comes first, followed by when to use it and what to do with the output. Every sentence earns its place, and there is no repetition of schema or annotation content.

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?

With only two optional, fully documented parameters and strong annotations, the definition covers selection, invocation, and output chaining. It states the output shape enough for an agent to pass podcast guids to show tools, so nothing critical 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?

The input schema already describes both parameters fully, including the default and cost caveat for resolve_shows. The description adds no parameter-level detail beyond what the schema provides, so the baseline score of 3 applies.

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 identifies the exact resource: recently published OP3 episodes that carry a podcast:transcript tag, newest first. It also states the operational purpose of finding machine-readable podcasts and implicitly distinguishes itself from download-focused sibling tools. This leaves no ambiguity about what the tool returns or why it exists.

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?

It clearly says to use this tool when the goal is reading transcripts or finding machine-readable episodes, and contrasts it with counting downloads. It also tells the agent that the returned podcast guids can be passed to the show tools. However, it does not name a specific sibling tool as the alternative, so the guidance is clear but not fully explicit.

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

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

Annotations already declare the operation safe and idempotent, and the description adds valuable behavior beyond that: it reports which identifier kind was recognized, accepts and encodes feed URLs automatically, and interprets failure as the feed lacking an OP3 prefix (meaning OP3 has no data). This gives the agent actionable expectations about behavior and failure semantics.

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?

Three sentences with no filler: purpose first, accepted inputs second, usage context and failure interpretation last. Every sentence earns its place, and the most important scoping information is front-loaded.

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 single-parameter, read-only resolution tool with rich annotations, the description covers input varieties, the output concept (uuid plus recognized kind), and the meaning of failure. No output schema exists, but the description still gives the agent enough to call the tool and interpret the result correctly.

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?

The schema already covers the single parameter fully with 100% coverage, including accepted formats and URL encoding, so the description does not need to add parameter detail. The description reinforces the input types but does not provide new semantic information beyond the schema.

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 a specific verb and resource ('Turn any podcast identifier into an OP3 show uuid') and enumerates the accepted input formats. It also positions the tool as the first step before other OP3 tools, distinguishing it from siblings that consume a resolved UUID.

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 when-to-use guidance ('Use this first when you have a feed URL and need the uuid every other tool wants') and explains what a failure means. It does not explicitly state when not to use it, such as when you already have the OP3 uuid, so it stops short of a full exclusion rule.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond annotations: it excludes bots and updates only once a day, which calibrate agent expectations about data freshness and composition. Doesn't overpromise a specific response shape.

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?

Tree compact sentences with no filler: first defines the payload, second gives usage guidance, third states caveats. Front-loaded with the most important distinguishing information.

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 tool is simple with one required parameter, no output schema, and annotations covering safety. The description tells the agent what values are returned, when to prefer it, how fresh data is, and what data quality caveats exist — enough to invoke it correctly.

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 only parameter, identifier, already documents accepted formats (uuid, podcast:guid, RSS feed URL). The description adds no extra meaning beyond the schema, so baseline 3 applies.

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?

Description states it returns a show's headline download metrics: 30-day total, week-by-week breakdown for four weeks, and weekly average. It also contrasts itself with 'raw query tools', helping an agent distinguish it from the many sibling aggregation and query tools.

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 explicit direction to prefer this tool over 'raw query tools' whenever it can answer the question, and notes it is a 'fast answer' to a common query. It doesn't name exact sibling tools or formally state when not to use it, but the category-level guidance and freshness limitation are useful.

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

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

Annotations already provide readOnly, idempotent, and non-destructive hints, so the bar is lower. The description adds valuable diagnostic behavior: it separates three externally identical failure cases and can say what is wrong. This goes beyond what the annotations alone convey.

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 front-loaded with the core purpose, follows with a clear trigger for use, and then explains the key diagnostic nuance. Every sentence contributes; there is no filler or redundancy.

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 read-only diagnostic tool with no output schema, the description sufficiently explains what the tool does, when to run it, what kinds of outcomes it distinguishes, and which input is most useful. An agent has enough context to select and invoke it correctly.

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 parameters are already documented. The description adds extra meaning by explicitly advising that a feed URL is the most useful input because the typical failure is that OP3 has never seen that feed. This guidance supplements the schema.

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 uses a specific verb: 'Check whether OP3 is actually receiving downloads for a show' and clearly identifies the resource. It also distinguishes this diagnostic tool from the many lookup/download siblings by explaining it is the first tool to run when numbers are zero or a show cannot be found.

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?

It gives explicit usage context: 'Run this first whenever the numbers are zero or a show cannot be found.' This is a clear trigger condition that guides tool selection, though it does not explicitly name alternatives or state when not to use it.

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