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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower, yet the description adds real operational context: the three-calendar-month restriction on the competing endpoint and why download share can be inflated by re-requesting apps. It does not discuss pagination, rate limits, or how the two metrics are computed, so not a full 5.

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, zero filler, and front-loaded: purpose first, then the routing rule versus the alternative, then the interpretation caveat. Each sentence earns its place by changing how an agent would call or read the tool.

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 carries some return-value burden and does name the two core columns (listener share, download share) and the windowing behavior. It stops short of describing the response shape, output format, or how windows outside the default are validated, leaving a small gap.

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 every parameter (identifier, start, end, top, bots) is already documented in the schema, establishing the baseline of 3. The description only alludes generally to 'any window you choose' and adds no per-parameter syntax or default detail 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?

States a specific verb+resource ('which podcast apps a show's audience uses'), the scope ('any window you choose'), and the returned metrics ('unique listeners alongside downloads'). It is clearly distinguishable from the global/aggregate siblings such as op3_global_app_share and op3_benchmark_apps.

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?

Explicitly names the alternative ('OP3's built-in app query') and the exact condition that selects this tool over it ('when the window matters, because OP3's own endpoint is locked to the last three calendar months'). It also guides interpretation, telling the agent that listener share is the more honest column versus inflatable download share.

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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuine interpretive context the annotations cannot: how to read downloadsPerListener, that values near 1 mean distinct people, and that higher values mean re-requests that inflate download counts elsewhere. It doesn't cover pacing/cost beyond the schema's note about raw rows.

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?

Purpose is front-loaded in the first clause and every sentence carries information. The second sentence is long and slightly rhetorical ("the number OP3's own dashboard ... cannot give you"), which costs a little tightness but not clarity.

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 must carry return-value meaning, and it does explain the key figure (downloadsPerListener) and its interpretation. It leaves the rest of the response shape unspecified, but for a read-only summary over a well-documented schema it is largely complete.

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 all four parameters are already documented in the schema (window formats, bots default, identifier types, slowness warning). The description adds no parameter-level detail beyond what the schema carries, so the baseline 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?

States a specific verb+resource+scope: unique listeners vs downloads for a show over any window, and explicitly distinguishes the result from what other rolled-up endpoints return. An agent can tell this apart from op3_show_downloads and op3_query_downloads without opening a 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?

Strong implicit routing: it says this is what the dashboard and every rolled-up endpoint cannot give you, telling the agent to reach for it when it needs people rather than requests. It stops short of naming the specific sibling to use instead (e.g. op3_show_downloads) when raw download counts are wanted.

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, destructiveHint=false and openWorldHint, so safety is covered. The description adds genuine interpretive context about what the index means and why min_share exists, but it says nothing about the shape or size of the returned result, pagination, or how many apps come back. With annotations carrying the safety profile, a 3 is appropriate.

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 four sentences and opens with the mechanics, which is reasonable, but 'This is the tool that turns app share into something actionable' is filler, and the 40% Apple Podcasts example is illustrative padding rather than operational detail. Roughly half the text 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?

With no output schema, the description carries the burden of explaining what the returned index means, and it does that well (100 = exactly average, raw share can mislead). Parameters are fully covered by the schema. It is largely complete for this tool, with only the output structure left implicit.

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 all five parameters (identifier, start, end, bots, min_share) are already documented in the schema, including the min_share rationale. The prose adds no syntax, format, or default information beyond what the schema provides, so the 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?

The description states a specific comparison: a show's app mix versus OP3's global mix, producing an index where 100 = average. That is a clear verb+resource an agent can act on. It does not, however, name or contrast itself with the obvious siblings op3_app_share and op3_global_app_share, so sibling differentiation is left to inference.

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 implies when the tool matters ('over-indexed apps are where this audience is unusual and where it can be reached deliberately'), which is interpretive guidance rather than routing guidance. There is no explicit statement of when to use this over op3_app_share, nor any exclusion or precondition. Usage is implied, not specified.

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, so the safety profile is covered. The description adds a genuinely useful behavioral fact not in the structured fields: OP3 accepts many shows per request, so comparison is one call rather than N.

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 tight sentences, front-loaded with what it does and what it returns, followed by the batching rationale and use cases. No filler or restatement of the name.

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, one-param read tool, the description covers purpose, metrics returned, ranking, and use cases. It could say more about the response shape (per-show rows vs aggregate), but it is complete enough to invoke 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% for the single parameter, including the 2–20 limit and the uuid/podcast:guid/feed URL formats, so the schema does the heavy lifting. The description's 'many shows in one request' only echoes the batching already documented 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?

States a specific verb (compare), resource (shows), and the exact metrics compared (monthly downloads, weekly average) with the ranking behavior called out. An agent can distinguish this from op3_show_downloads (single show) or op3_benchmark_apps without opening a 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 clear use cases: benchmarking a show against category peers and tracking a portfolio at once. It does not explicitly name the single-show alternative (op3_show_downloads) as the when-not path, but the multi-show framing implicitly excludes it.

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, so the safety profile is covered. The description adds useful context that all four dimensions arrive in one call, but says nothing about result volume, ordering, or how the bot filter interacts with agentType beyond what the schema already states.

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, front-loaded with the resource and dimensions, and the payoff ('one call returns all four') lands before the qualifier. Slightly dense in the enumeration, but no sentence is 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 call with no output schema but full param documentation, the description covers the what, the return shape (four dimensions at once), and an implied use case. Nothing critical is missing 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?

Schema description coverage is 100%, setting a baseline of 3. The description goes beyond the schema by decoding what agentType, agentName, deviceType and deviceName actually mean with concrete example values, which the raw enum-less parameters do not convey on their own.

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 outcome ('how a show is consumed') and enumerates the four dimensions it returns (agentType, agentName, deviceType, deviceName), so the agent knows exactly what comes back. It also implicitly separates itself from single-dimension siblings by noting it returns all four 'rather than a single ranked list.'

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 line 'which is what you want for a picture of the audience rather than a single ranked list' gives a clear situational cue and implicitly contrasts with the narrower siblings (op3_app_share, op3_geography). It stops short of naming an explicit alternative to use instead, so it never reaches when/when-not territory.

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/non-destructive/open-world, so the safety profile is covered. The description adds genuinely non-obvious behavioral detail: how growth is computed (halves of the window, not endpoint-to-endpoint) and why (weekly seasonality), which materially affects how an agent should interpret 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?

Two front-loaded sentences: the first states the output, the second justifies the growth methodology. Every clause earns its place, though the seasonality rationale is somewhat verbose relative to the tool-selection job the description is doing.

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 carries the return-value burden and does so: downloads, unique listeners, growth rate, and peak period. Combined with 100%-covered params and full annotations, an agent has everything needed to call and interpret this tool without opening anything else.

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%, including the accepted identifier formats, relative date syntax, bots default, and granularity guidance, so the baseline is 3. The description's 'bucketed by day, week or month' restates the enum without adding syntax, format, or constraint detail 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 names the exact resource and shape of the analysis: a show's downloads and unique listeners over a window, bucketed by day/week/month, plus growth rate and peak period. That specificity implicitly separates it from aggregate siblings like op3_show_downloads or op3_episode_downloads, but no sibling is named, so an agent still has to infer the boundary.

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?

There is no explicit when-to-use, when-not-to-use, or alternative tool callout, despite several overlapping siblings (op3_show_downloads, op3_query_downloads, op3_episode_downloads). The only usage hint — 'use week or month for windows longer than a couple of months' — lives in the schema for granularity, not in the description.

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, non-destructive and open-world, so safety is covered. The description adds real behavioral value beyond that: it discloses the return shape (cumulative downloads by day, median, verdict) and the median's inclusion rule (only episodes at least as old as the horizon qualify), which is non-obvious logic an agent could not infer.

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 core purpose is front-loaded in the first sentence, followed by return contents and rationale. It runs a bit long with three sentences and the final clause is dense, but each sentence carries distinct information, so nothing is pure padding.

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 must carry the return-value burden, and it does describe the key outputs (cumulative curve, median, verdict) and the median's construction rule. It omits some details like the verdict's possible values or output format, but it is sufficient for an agent to call the tool 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 coverage is 100%, so the baseline is 3, but the description earns above baseline by explaining how horizon_days and compare_episodes behave conceptually — the horizon gate on median membership and the trade-off between steadier and slower comparisons. It adds interpretive meaning rather than merely 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 states a specific verb and resource — tracking one episode's cumulative downloads against the show's own median at the same age — and frames it as a comparison tool, which cleanly separates it from siblings like op3_episode_downloads or op3_show_downloads that report raw totals. An agent can identify the tool's distinct job without opening the 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?

It gives clear guidance on when to reach for this tool — judging a recent episode fairly — and explains why raw total downloads are the wrong lens. However, it never names the alternative tools (e.g. op3_episode_downloads) an agent should avoid, so routing is inferred rather than 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds genuinely useful operational context: an empty result means OP3's daily rollup hasn't covered the show yet, not that data is absent. It doesn't discuss latency, rate limits, or refresh cadence.

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, all front-loaded with the metric list first, then the use case, then the empty-result caveat. Nothing is redundant with the title or schema.

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 naming the return metrics and the empty-result case, which is what an agent most needs. Minor gaps remain around per-episode fields returned and result ordering, though ordering is in the schema.

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 both parameters (identifier formats, limit default/max, newest-first ordering) are fully documented in the schema. The description adds no syntax or format detail beyond that, so the 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?

States a specific verb+resource (per-episode download counts for a show's recent episodes) and enumerates the exact metrics returned (1, 3, 7, 30-day and all-time). This distinguishes it from show-level siblings like op3_show_downloads and the flexible op3_query_downloads without opening either 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?

"Use it to compare how episodes performed at equal age" gives a clear selection criterion, and the empty-result note preempts a common misuse (treating no data as an error). It stops short of naming an explicit alternative for show-level or raw download queries, so no when-not routing.

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, so safety is covered. The description adds genuinely non-obvious analytical behavior: that the symmetric similarity is misleading for skewed pairs and the smaller side's share is the decisive read. That interpretation context is real value 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?

Front-loaded with the purpose in one sentence, then a second sentence covering returns and interpretation. It is longer than minimal but each clause (shared listeners, symmetric similarity, smaller-side share, spike interpretation) carries information an agent needs.

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 competently documents the three returned values and how to interpret them. It does not mention default window or bot handling, but those are fully covered by the schema, so the remaining gap is small.

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 window, bots, identifier and top_episodes are fully documented in the schema itself. The description only alludes to 'busiest episodes', which maps loosely to top_episodes, adding no format or syntax detail 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?

Names a specific analysis (pairwise audience overlap among a show's busiest episodes) and enumerates the three metrics returned: shared listeners, symmetric similarity, and smaller-side share. This is clearly distinguishable from siblings like op3_episode_downloads (single-episode volume) and op3_compare_shows (cross-show comparison).

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?

Usage is implied rather than stated: the guidance about 'one big episode and one small one' tells the agent the tool fits asymmetric episode pairs, but nothing says when to prefer this over op3_listener_retention, op3_new_vs_returning, or op3_episode_downloads. No explicit alternatives or exclusions are given.

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/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: it reports downloads and unique listeners side by side, and explains that region/metro are qualified by country so same-named places don't merge.

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 purpose, and the market-size rationale for dual metrics earns its place. Slightly conversational but no filler that obscures the operative facts.

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?

No output schema exists, so the description carries the return-value burden and does so by naming the two reported metrics per place. It omits pagination/otherCount handling and default window behavior, but those are already documented in the schema.

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 baseline is 3. The description adds rationale the schema lacks — why two metrics are returned together, and why region/metro results are country-scoped — which helps the agent interpret level choices rather than just enumerate them.

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?

Opens with a specific verb+resource ('Where a show's downloads come from') and enumerates the exact geographic levels available, which cleanly separates it from siblings like op3_audience_summary or op3_device_breakdown. An agent can identify the tool's job without opening the 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?

The description frames the tool as answering at whatever granularity you request and lists the five levels, giving clear context for when each is appropriate. It does not name a sibling alternative or state exclusions, so it stops short of a 5.

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, so safety is covered. The description adds useful context the annotations lack: that include_episodes is off by default because long-running shows return hundreds of episodes, i.e. a payload-size warning, plus the id-chaining contract for episode-level tools.

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 lookup, then the optional expansion, then the downstream chaining note. Every sentence carries information, though the include_episodes clause partially repeats the schema's own description of that flag.

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 naming the returned fields (uuid, title, podcast guid, stats page) and the shape of the episode list (ids, titles, publication dates). It is nearly complete for a lookup tool; only the form of the 'public stats page' value is left implicit.

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 identifier, episode_limit and include_episodes are already fully documented in the schema. The description only restates the include_episodes behavior ('also get the episode list'), adding no syntax or format detail beyond what the schema provides. 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?

The description gives a specific verb (look up) and resource (a show) and enumerates what comes back: uuid, title, podcast guid and public stats page. That is well beyond a restatement of the name. It does not explicitly distinguish itself from the sibling op3_resolve_show, which is the one nearby tool an agent could confuse it with.

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 tells the agent to set include_episodes when the episode list is needed, and states that 'Episode ids from here are what the episode-level tools filter on' – a genuine routing hint toward the episode-level siblings. It does not say when to prefer op3_resolve_show or op3_list_episodes instead, so the guidance is clear but not exhaustive.

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 non-destructive, so safety is covered. The description adds meaningful behavior beyond that: a fixed 30-day window, an all-shows aggregation scope, and the ability to narrow to a single device.

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 scope and time window, each carrying information. 'It is useful on its own' is slightly padded but not wasteful.

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?

Discloses the fixed time window, the aggregation scope, and device narrowing, and the schema fully documents the two optional params. Without an output schema, a brief note on the return shape (app names + share percentages) would round it out.

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 both optional params are already documented in the schema. The description adds only mild context about what narrowing by device reveals, so the baseline 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?

States a specific verb+resource+scope: 'Podcast app market share across every show OP3 measures, over the last thirty days.' It also explicitly distinguishes itself from a per-show tool ('not one show's numbers'), which is critical given the sibling op3_app_share.

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 clear usage context ('useful on its own for questions about the podcast app landscape') and contrasts with per-show data. It stops short of naming the alternative tool (op3_app_share or op3_benchmark_apps), so the routing is implied rather than 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 readOnly, idempotent, openWorld, and non-destructive, so safety is covered. The description adds meaningful domain context beyond the structured fields: it explains that the tool returns TWO rates with distinct interpretations and clarifies what each is a share of, which helps the agent reason about results rather than just the operation.

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?

Purpose is front-loaded in the first clause, followed by parallel definitions of the two rates. Four sentences, each carrying interpretive weight, with no filler. Slightly longer than strictly necessary but 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?

With no output schema, the description properly carries the burden of explaining return values, and it does so clearly for both metrics. The remaining gap is the lack of sibling routing and any note on empty-cohort behavior, but for a read-only analytics tool it is essentially complete.

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 five parameters including the period defaults. The description mentions 'two periods' generically but adds no syntax, format, or reconciliation detail (e.g., how cohort_end relates to later_end), so the baseline of 3 is correct.

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 resource and analysis (cohort carry-over between two periods) and even names the two output metrics, retentionRate and carryOverShare, so the agent knows exactly what this computes. However, it never differentiates from close siblings like op3_new_vs_returning, which likely cover adjacent territory, so it stops short of a 5.

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 what each rate measures and that a show can score well on one and badly on the other, which implies interpretive use. But it gives no explicit when-to-use guidance, no exclusions, and no routing to alternatives such as op3_new_vs_returning or op3_audience_summary.

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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower. The description adds genuine interpretive context the annotations cannot: that the data is request timing rather than true listening, and that app background-refresh defaults inflate certain peaks. That caveat materially affects how an agent should present the result. It stops short of 5 only because it says nothing about aggregation/window limits beyond what the schema already notes.

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 what the tool returns, then the use case, then the critical caveat. Every sentence earns its place; nothing is redundant with the schema or annotations.

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 carries the burden of describing the return shape, and it does so (hour-of-day and day-of-week buckets, UTC). It is complete enough to call and interpret correctly. It could say more about output structure (counts vs. relative shares) but 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% — identifier, start, end, and bots are all documented in the schema, including the rationale for leaving bots off. The description adds no parameter-level information beyond that, so the baseline 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 states precisely what is returned — download timing broken down by hour of day and day of week, in UTC — which is a specific verb+resource+granularity statement. It also resolves the mismatch between the tool name ('listening patterns') and what it actually measures. It does not explicitly name the sibling it differs from (e.g. op3_show_downloads or op3_download_trend), so it falls short of a 5.

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?

'Useful for choosing a publication slot' gives one concrete use case, which is more than a bare description. However, there is no guidance on when NOT to use it or which sibling tool answers a related question (e.g. total downloads vs. time-of-day distribution). Usage is implied rather than delineated.

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, openWorldHint and destructiveHint=false, so safety is fully covered. The description's only genuinely new behavioral detail is the provenance warning that episode titles are third-party RSS text (a mild injection caution); the newest-first ordering merely restates the schema. Adequate but not rich 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 tight sentences, zero padding, with the core purpose and ordering front-loaded before the usage hint and the provenance caveat. Every sentence carries information an agent needs.

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 does the necessary work by naming the returned fields and sort order. It does not mention pagination or whether a limit truncation is signalled, a minor gap for a list tool with a 500-item cap, but otherwise complete.

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%, with all three parameters documented (identifier formats, limit default/max, case-insensitive substring search applied before limit). The description adds no parameter detail beyond the schema, so the baseline 3 is correct.

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 ('List a show's episodes') and enumerates the returned fields (OP3 episode ids, titles, publication dates) plus ordering (newest first). This clearly separates it from siblings like op3_get_show (show metadata) and op3_episode_downloads (metrics), so an agent can pick it without opening a 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: resolve an episode id before calling anything episode-level, which correctly routes the agent toward this tool as a prerequisite step. It does not, however, name an alternative for the aggregate-analytics case or state exclusions, so it falls short of the 5 bar.

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 read-only, idempotent, non-destructive behavior, and the description adds useful context beyond that: the default baseline multiplier and why it matters, that both sizes are returned, and that wider windows read raw rows and are therefore slower. 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?

Four compact sentences, front-loaded with what the tool computes before the caveat about baseline length. Every sentence carries information; only the final clause slightly restates the reporting behavior.

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 does tell the agent that both the first-time and returning sizes are returned, which is the key shape information. It leaves the exact response structure unspecified, but for a read-only analytical tool with full schema coverage this is nearly complete.

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 baseline is 3; the description still adds interpretive value by motivating baseline_multiplier's default (a short baseline mislabels a monthly listener as new) and reinforcing the multiplier semantics. It does not add format detail for start/end/identifier 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?

States a specific analysis: splitting a show's listeners in a window into first-time vs returning via comparison against a prior baseline. The framing ('reaching new people or serving the same audience repeatedly') conceptually separates it from a retention-style metric, though it never names a sibling tool to route against.

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?

Explains the question this answers and adds guidance on the key tradeoff (baseline length changes what counts as 'new'). It does not explicitly say when to prefer this over op3_listener_retention or op3_audience_summary, so the routing decision is left partly implicit.

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 cover readOnly/idempotent/non-destructive, and the description adds non-obvious behavior the annotations cannot: rows return oldest-first with no reversal option, limit therefore takes the earliest rows, raw rows are costly, and per-listener identifiers are stripped from output. These are exactly the traits an agent needs before calling.

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?

Front-loaded with purpose, then exclusions, then the ordering/limit caveat, then the privacy note. Every sentence carries distinct, decision-relevant 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?

For a wide raw-row endpoint with no output schema, it covers ordering, scoping, cost and PII removal well, which is most of what matters. The one gap is that it never indicates what columns or fields the raw rows actually contain, leaving the agent to discover the row shape blind.

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% and the schema itself explains bots, limit and include_listener_keys well, so the baseline is 3. The description adds meaning the schema does not: the coupling between start and limit (limit takes the earliest rows in the window) and the privacy consequence of the listener-key parameter. It does not restate parameter formats, which 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+resource ('raw download rows for a show') and positions itself precisely as the escape hatch beyond the aggregating tools. It names four sibling tools it is not, so an agent can route correctly 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?

Explicit when-to-use-vs-alternatives: prefer op3_show_downloads, op3_audience_summary, op3_geography or op3_app_share when they suffice, with the reason (raw rows are slow to fetch and expensive to reason over). It also gives the correct workaround for recent activity (narrow with start rather than raising limit), which is real operational 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description still adds real behavioral value beyond that: it discloses that this is the lowest-level surface OP3 exposes and enumerates what a row contains (user agents, byte ranges, serving edge). It does not discuss volume/rate behavior, which is the only gap.

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 what the tool returns, then its role, then the routing rule. Every sentence carries distinct information with no restatement of the title or schema.

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, and the description compensates by describing the shape of the returned rows (individual requests, user agents, byte ranges, edge). Combined with the 100%-covered input schema and the safety annotations, an agent has everything needed to call and interpret this 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 schema already documents all five parameters including the wildcard url behavior and the default time window. The description's 'unless filtered by url' duplicates the schema rather than extending it, so the 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?

States a specific verb+resource ('raw request rows from OP3's redirect log') and immediately scopes it ('across every show unless filtered by url'). It also positions the tool against the analytics siblings by calling itself a 'verification surface rather than an analytics one', so an agent can distinguish it without opening a 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?

Explicitly says when to use this (low-level verification, individual requests) versus when not to ('For questions about a specific show's performance, use the show tools instead'). Both the use case and the alternative are named, leaving nothing to inference.

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, non-destructive, open-world. The description adds return-format context (podcast guids that feed the show tools) and ordering (newest first), plus the resolve_shows cost note. It doesn't state rate limits or pagination, but adds useful behavior 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 tight sentences, front-loaded with the resource and scope before the usage guidance. Every sentence contributes, though the final sentence is a mild restatement of the return value already implied by the tag/guid framing.

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?

No output schema, but the description explains what is returned (newest-first episodes with podcast guids usable by the show tools). Annotations cover the safety profile. Combined with 100% schema coverage, an agent has enough to call it correctly, though return field detail is thin.

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 both parameters are already well documented. The description connects the returned guids to the show tools, which hints at the resolve_shows use case, but does not add syntax or defaults beyond the schema. 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?

States a specific verb+resource+scope: recently published episodes across all of OP3 carrying a podcast:transcript tag, newest first. This clearly distinguishes it from the sibling download/audience tools, which the description explicitly contrasts against ("read transcripts rather than count 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?

Provides clear when-to-use context: find podcasts with machine-readable episodes, the shortlist for anything that needs to read transcripts. It contrasts the use case against download-counting siblings, but doesn't name a specific alternative tool the way the top-tier example does, so it stops short of explicit routing.

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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds genuinely useful context: it reports which identifier kind was recognized, and it explains what a failure implies (the feed lacks the OP3 prefix, so OP3 has no data). This failure-mode disclosure goes 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 short sentences, front-loaded with the core purpose, then usage ordering, then failure interpretation — every sentence earns its place with zero 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?

No output schema exists, so the description wisely notes that the response reports which identifier kind was recognized. For a single-param resolver with full annotation coverage this is nearly complete, though it could say more about the returned uuid payload 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% and the schema already documents the three accepted identifier forms with format detail (32 hex chars, dashed GUID, URL). The description restates the same three forms at a coarser level, adding little beyond the schema. 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?

States a specific transformation ('turn any podcast identifier into an OP3 show uuid') and enumerates the accepted identifier kinds, so the agent knows exactly what the tool does. It is clearly distinct from siblings like op3_get_show (which presumably consumes a uuid) and op3_verify_prefix.

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?

'Use this first when you have a feed URL and need the uuid every other tool wants' gives an explicit ordering and trigger condition relative to siblings. It also explains the failure case (no OP3 prefix, hence no data), which is strong guidance, but it does not name a specific alternative tool to try instead.

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 cover read-only/idempotent/non-destructive semantics, so the bar is lower; the description adds genuinely new behavior: bot exclusion and once-a-day refresh, both of which affect how an agent should interpret and trust the numbers. It does not cover pagination or error behavior, but for an aggregate read this is solid.

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 tight sentences: what it returns first, then the routing rule, then the behavioral caveats. Every sentence carries information and nothing is padded.

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 must describe the return payload, and it does so concretely (last 30 days, four-week weekly breakdown, weekly average). Combined with annotations and a fully documented parameter, an agent has everything needed to call and interpret 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% and the single identifier parameter is fully documented (uuid, podcast:guid, or RSS URL) in the schema. The description adds no further parameter meaning, so the 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?

States a specific resource (a show's headline download numbers) and enumerates exactly what is returned: 30-day downloads, four-week week-by-week breakdown, and weekly average. This clearly distinguishes it from siblings like op3_episode_downloads, op3_download_trend, and op3_query_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?

Explicitly says it 'should be preferred over the raw query tools whenever it can answer the question,' which gives a positive selection rule and names the alternative category. It stops short of naming specific sibling tools or stating when this tool is NOT sufficient (e.g. custom date ranges).

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, so the safety profile is covered. The description adds genuine behavioral value beyond that: it explains that the tool actively diagnoses and reports what is wrong, and enumerates the three distinct states it disambiguates. Output format specifics are still absent, but the diagnostic behavior is well disclosed.

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 purpose, then the routing trigger, then the disambiguation detail. Tight and every sentence carries information, though the third sentence is somewhat elaborate for the point it makes.

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 should convey what comes back; it does so at the level of outcomes (one of three cases plus a diagnosis of what is wrong). Annotations cover safety and the schema covers both parameters, so the remaining gap — the exact shape of the returned diagnosis — is minor.

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%, including a detailed note that a feed URL is the most useful identifier because the failure is usually that OP3 has never seen the feed. The description reinforces the feed/prefix framing but adds no syntax or format detail beyond the schema, so the 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?

The description states a specific verb and resource — checking whether OP3 is receiving downloads for a show — and frames the tool as a diagnostic rather than an analytics query, which cleanly separates it from siblings like op3_show_downloads or op3_query_downloads. It even names the failure modes it distinguishes, so an agent knows exactly what question this tool answers.

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?

"Run this first whenever the numbers are zero or a show cannot be found" gives an explicit, actionable trigger condition, plus the implicit converse that it is not the tool to reach for during normal analysis. It does not name alternative sibling tools for adjacent cases (e.g. op3_resolve_show for identifier resolution), so it falls short of a full when/when-not/alternatives statement.

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