op3_global_app_share

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.