Apple Search Ads share of voice

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond that: the iOS-only constraint and the data-shape quirk that by=history returns a dict keyed by app-id string that is flattened here. It omits cost/rate-limit behavior, though dry_run is documented in the schema.

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 parallel, front-loaded clauses map one-to-one onto the enum values, followed by a single constraint sentence. No filler, no repetition of structured fields, and the highest-value information (mode semantics) comes first.

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 10-parameter read-only query tool with no output schema, the description covers the hardest gap (undocumented enum semantics), the platform limitation, and a known response-shape gotcha. Nothing essential to correct invocation appears to be 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 'by' enum values are completely undocumented in the schema, and the description is the only place their semantics are defined; it also restates the conditional requirements for term and app_id. The remaining parameters (fields, format, limit, country, dry_run, dates) are left to the schema, which covers them at 70%.

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 specific resource (Apple Search Ads share of voice) and enumerates the three distinct query modes (by=term, by=app, by=history) with a one-line statement of what each returns. An agent can tell what it does without opening the schema, though it does not explicitly differentiate itself from siblings like sensortower_keywords or sensortower_top_advertisers.

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 selection guidance by mapping each mode to an intent: 'who is buying ads on a search term' vs 'which terms an app buys' vs 'one app's daily share of voice on one term'. It also states the platform boundary (iOS only, no Android equivalent). It stops short of naming when to prefer a sibling tool instead.

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