sonar

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), and the description adds non-obvious requirements not in the schema: an Indie plan (trials count) and an authorized account or write-scope API key. This is genuine additional context beyond structured fields.

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 tight sentences: the action and its ordering behavior come first, followed by prerequisites. Every clause 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 two-parameter append tool with no output schema, the description covers action, ordering, prerequisites, and auth. An agent has enough to invoke it correctly, though it doesn't describe the resulting state or any limits on set size.

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 (set_id and layout) are already documented, including the 'omit for a blank screen' hint. The description adds nothing parameter-specific, 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 precise verb (append) and resource (a screen to a screenshot set), with the append-at-end semantics made explicit. It also names the sibling sonar_update_screenshot_set for reordering, clearly distinguishing it from create/update/delete screenshot 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?

Explains that the new screen is appended at the end and points to sonar_update_screenshot_set when reordering is needed, which is useful routing. It does not, however, state when to prefer this over creating a new set or other alternatives 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 readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered; the description adds information the annotations cannot express: the read is free (no analysis credits consumed), it is plan-gated to Indie/Agency, and it returns `analysis: null` rather than erroring when no analysis exists. That null-vs-error distinction is the key behavioral fact for correct agent handling.

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?

A single dense sentence that front-loads the return payload, followed by short clauses for the fallback, cost and plan gate. Slightly awkward mid-sentence dash construction for the sibling routing, but no sentence is wasted.

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 still enumerates what comes back (analysis fields plus video transcript) and covers the null case, cost, and plan prerequisite. Nothing an agent needs in order to call this correctly and interpret the result 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 coverage is 100% and the `creative_id` field already spells out that it is the Sonar id from sonar_ad_spy_ads, not the Meta `ad_id`. The description adds nothing about the parameter, so the baseline 3 applies — the schema carries the full parameter burden.

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 scope: the cached AI analysis of an ad (hook, angle, format, structure, CTA, why it works) plus its video transcript, and explicitly names the empty case (`analysis: null`). It also names the sibling sonar_ad_spy_analyze_ad as the counterpart, so an agent can separate the cached read from the analysis-generating tool 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?

Gives an explicit routing rule: if the result is null / not yet analyzed, call sonar_ad_spy_analyze_ad instead. It also states the access condition (Indie or Agency plan, trial counts) and that the call is free, which are the two conditions an agent needs before choosing 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?

Goes well beyond the readOnly/idempotent annotations: discloses that no spend or impression data exists outside the EU, that longevity and variant counts are the substitute signals, that media URLs are expiring CDN links and library_url is the permanent one, and what refresh_due=true implies. The compact/full payload tradeoff and plan gating are exactly the kind of context annotations cannot carry.

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-loads what is returned, then moves to signals, payload shape, freshness, and access requirements in a logical order. The compact-vs-full point is stated twice (parenthetical plus the media URL sentence), which is minor redundancy in an otherwise dense, purposeful block.

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 9-parameter read tool with no output schema, the description fully describes the return surface (stats block, filtered ads, daily history) and flags the key constraints (EU-only reach data, expiring media, plan requirement). Nothing an agent needs in order to call it and interpret the result 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 coverage is 100%, so the baseline is 3; the description still earns credit by explaining why min_days matters (longevity is the honest winner signal, 30/60/90) and the size/expiry tradeoff between compact and full. It adds interpretive value on top of an already well-documented schema rather than restating it.

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 — a Facebook page's cached Meta ads — and enumerates the payload (ad stats, filtered ads with copy/CTA/landing URL/placements/days running/longevity tier, daily active-new history). It names related siblings (sonar_ad_spy_refresh, sonar_ad_spy_competitors, sonar_ad_spy_open_page) by role, so an agent can place it in the family without opening other 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?

Explains the acquisition path (cached read; refresh via sonar_ad_spy_refresh when refresh_due is true) and states the plan prerequisite (Indie or Agency, trial counts). It does not explicitly contrast itself with sonar_ad_spy_ad_analysis or sonar_ad_spy_analyze_ad, which are the closest siblings, so the when-not guidance is incomplete 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 only declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false; the description goes well beyond that by disclosing the caching model, the 'cached: true' marker on repeat calls, the cost (one of the account's daily Ad Spy lookups, consisting of a video transcript plus one AI call), and the plan/auth prerequisites. It also sets a scope boundary — no invented metrics — so the agent knows the analysis is grounded in the ad's actual content.

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 WRITE label and the output contents, then cost/caching, then prerequisites — a sensible ordering that matches how an agent decides and executes. It is dense but every clause carries operational information; the only minor cost is the length of the parenthetical describing the lookup's composition.

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 one-parameter tool with no output schema, the description covers everything an agent needs: what is produced, what an existing cached entry looks like in the response, what the call costs, and what entitlements are required. The absence of an output schema is compensated by the enumerated result fields.

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?

There is a single parameter and schema description coverage is 100%, with the schema itself clarifying that creative_id is the Sonar ad id from sonar_ad_spy_ads rather than the Meta ad_id. The description adds no additional parameter guidance, so the baseline of 3 applies — the schema carries the load.

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 (analyze/generate a breakdown) and resource (a competitor ad) and enumerates the concrete output sections: hook, persuasion angle, creative format, beat-by-beat structure, CTA, and a grounded 'why it works'. It explicitly labels itself a WRITE tool, distinguishing it from the sibling sonar_ad_spy_ad_analysis, which by name reads as a retrieval counterpart.

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 qualifying conditions — requires an Indie/Agency plan (trial counts) and an authorized account or write-scoped API key — plus the practical rule that already-cached ads come back free instead of consuming a lookup. It does not explicitly name sonar_ad_spy_ad_analysis as the cheaper read path, so the routing to that sibling is left inferable rather than stated.

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, but the description adds behavior the annotations cannot: the response is cached, and the call is gated behind an Indie or Agency plan (a trial counts). It also explains that a usage allowance with used/limit/remaining/resets_at is returned, which tells the agent to watch for quota exhaustion.

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 short sentences, front-loaded with the routing purpose before the payload detail and the plan caveat. Every clause carries information: what it returns, what to do when data is missing, and what the call costs.

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 burden falls on the description to describe returns, and it does so field-by-field along with the plan and quota prerequisites. Nothing an agent needs in order to call this zero-arg tool or interpret its result 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?

Zero parameters, so the schema baseline is 4 and there is nothing parameter-level to explain. The description does add value by naming the response fields (meta_pages, tiktok_accounts, allowance counters) an agent should look for, even though these are outputs rather than inputs.

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 (every competitor the account tracks) and enumerates exactly what comes back: linked meta_pages, tiktok_accounts, last page scan, and today's lookup allowance. The opening 'Start here for competitor ads' positions it against the many sibling ad_spy tools without ambiguity.

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 entry point ('Start here'), plus a concrete routing rule for the edge case: a competitor with no linked page needs sonar_ad_spy_scan then sonar_ad_spy_link. Names the alternative tools and the condition that selects them, so the agent never has to guess a next step.

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=false, idempotentHint=true and destructiveHint=false, and the description adds genuinely new behavior: the effect is account-scoped only ('other accounts still see them'), the change is reversible via hidden:false, and there are plan and auth-scope gates. It does not describe the response payload, but that is minor given the safety profile is well covered.

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 tight sentences, front-loaded with the write/mutation marker and the primary action, followed by the scoping and prerequisite details. No filler or 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 two-parameter mutation with full schema coverage and annotations, the description covers scope, reversibility, and access requirements. The only gap is the absence of any statement about the return value, which matters slightly since no output schema exists.

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 documented, including the hidden default and the warning to use Sonar ids rather than Meta ad_id. The description only restates the restore semantics with 'hidden: false' and adds nothing about batch limits or id sourcing 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?

Opens with an explicit 'WRITE tool' marker, then states the specific verb+resource: remove ads from this account's scans, with the inverse operation (hidden: false) named in the same sentence. An agent can distinguish this from read-oriented siblings like sonar_ad_spy_ads 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?

Gives real operational preconditions — per-account scope, Indie/Agency plan (trial counts), authorized account or write-scoped API key. It does not name an alternative tool or state when-not to use it, 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 only declare write/idempotent/non-destructive; the description goes further by disclosing that the mapping is shared across every Sonar account (a global side effect the agent must not treat as private), that the call spends no lookup credit, and that it requires an Indie or Agency plan plus an authorized account or write-scoped API key. These are exactly the behavioral facts an agent cannot infer from structured 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?

Four tight sentences: the write framing and eligibility come first, then the preconditions, then cost and the follow-up call, then auth/plan requirements. Every sentence carries a distinct, actionable constraint 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 write tool with six parameters, no output schema, and only partial annotation coverage, the description supplies the two things annotations cannot: permission/plan prerequisites and the cross-account blast radius of the mapping. An agent has everything it needs to decide whether to call it and what to do afterwards.

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 per-field channel/page_id/user_id/account_id/advertiser_id semantics are already documented. The description still adds real meaning by constraining which ids are acceptable (own scans or searches, within 2 days), which the schema does not express. It does not restate the meta-vs-tiktok parameter split, but that is thoroughly covered 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 (confirm/link) and resource (a Facebook page or TikTok account to a competitor), and immediately frames it as a WRITE tool. It is clearly distinguished from its sibling sonar_ad_spy_unlink and from the read-side discovery tools (sonar_ad_spy_scan, sonar_ad_spy_search_pages) it depends on.

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 precondition ('Only call it after the user picked the candidate') and names the next step ('then use sonar_ad_spy_refresh to fetch the ads'), which routes the agent through the whole workflow. It also states the hard eligibility rule that only candidates returned by this account's own scans/searches in the last 2 days are accepted.

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 only declare write/openWorld/non-idempotent/non-destructive; the description adds the substantive behavior an agent cannot infer: a 24h cache refresh threshold, consumption of one daily Ad Spy lookup, free same-page-account-ad re-opens within a day, and the degraded path past the allowance (cached copy with meta.stale plus a meta.note the agent is told to relay). It also discloses plan and authorization prerequisites.

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 sentences, front-loaded with the WRITE marker and the action, then cost, then failure mode, then prerequisites. Every clause carries information, though the final sentence packs quota, cache, plan, and auth into one dense run that could be split for scanability.

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 write tool with 8 params and no output schema, the definition covers everything an agent needs: where page_id comes from, what the returned payload looks like via the sonar_ad_spy_ads reference, what stale results look like, what the call costs, and what account/plan state is required.

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 enums and ranges already documented for all 8 parameters, so the schema carries the load. The description adds only a pointer that filters match sonar_ad_spy_ads and a note that page_id derives from search_pages/scan — useful framing but no per-parameter semantics beyond structured data.

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 'WRITE tool' then a specific verb+resource: open a Facebook page from a recent search or scan and return its ads. It explicitly distinguishes itself from the linking flow ('without linking it to a competitor') and anchors the response shape to sonar_ad_spy_ads, so an agent can place it among sonar_ad_spy_link, sonar_ad_spy_ads, and sonar_ad_spy_refresh 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?

States the entry condition clearly: the page_id must come from a recent search or scan (last 2 days), and the tool is the non-linking path. Cost conditions are spelled out (one daily lookup, same-day re-opens free, plan and scope requirements). The alternative tool is implied rather than named — it never says 'use sonar_ad_spy_link if you want competitor tracking' — so it falls just short of explicit when/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 only say write/non-idempotent/open-world; the description goes well beyond by disclosing quota mechanics (one daily Ad Spy lookup, free same-day re-opens, allowance visible via `allowance` from sonar_ad_spy_competitors), the over-quota fallback (`meta.stale` plus `meta.note` to relay), and plan/auth prerequisites. No contradiction with readOnlyHint=false or destructiveHint=false.

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 write nature and the freshness trigger, then quota, fallback, and auth in descending priority; every sentence carries information. It is a single dense paragraph with stacked parentheticals, which costs a little readability but not 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 params, full schema coverage, and no output schema, the description covers what remains: return shape (same view as the sibling read tools), failure-mode payloads (`meta.stale`/`meta.note`), cost model, and authorization requirements. An agent can decide and call correctly from this alone.

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 both parameters are documented there, including the meta/tiktok enum meanings and the id source. The description only restates the provenance of `id` (from sonar_ad_spy_competitors) rather than adding new constraints, 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 first clause names a specific verb (refresh/fetch) plus the two resources (Meta ads, TikTok videos) and scopes it to stale cache. It explicitly tells the agent it returns the same view as sonar_ad_spy_ads / sonar_ad_spy_tiktok_posts, so the difference from those siblings is unambiguous.

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 states the trigger condition (cached copy over 24h old), the no-op case ('a fresher copy comes back unchanged and costs nothing'), and the free same-day re-open case. Alternatives are named directly via sonar_ad_spy_ads / sonar_ad_spy_tiktok_posts, leaving nothing material 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 readOnlyHint=false, openWorldHint=true and idempotentHint=false, so the write/open-world nature is covered structurally. The description goes well beyond them by disclosing quota consumption, the free-repeat cooldown, cached stale responses with a `meta.note` to relay, and plan/auth requirements — genuinely useful operational context. It stops short of describing the candidate list shape or how ranking works, so a 3 rather than higher.

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 "WRITE tool" marker and the core action before operational caveats. Dense with parentheticals (cooldown, allowance, plan requirement) which are individually load-bearing but make the prose heavier than it needs to be.

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 three-parameter write tool with no output schema, the definition covers the action, the follow-up workflow, cost/quota behavior, cached-result fallback, and access requirements. Nothing an agent needs in order to invoke it correctly and interpret the outcome 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%, and all three parameters carry their own descriptions including the channel enum. The description reinforces channel semantics ("meta" for Facebook, "tiktok" for TikTok) but adds no syntax or format detail beyond the schema, 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?

Opens with a specific verb plus resource ("search a competitor's Facebook page ... or TikTok account") and names the return shape (ranked candidates with a `best_match` flag). It explicitly negates the neighboring capability ("never links"), so an agent can separate it from sonar_ad_spy_link and sonar_ad_spy_search_pages 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?

States the follow-up action explicitly: show candidates, let the user confirm, then call sonar_ad_spy_link, with the rationale that the mapping is account-shared. It also gives exclusions and edge conditions (unambiguous top match, free 24h cooldown replay, same-day re-open free, stale fallback past allowance), which is the full when/when-not picture.

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?

Goes well beyond the annotations (which only flag non-read-only, non-idempotent, closed-world) by disclosing that every call is a fresh AI generation, consumes one daily Ad Spy lookup plus an extra lookup for a first-time ad analysis, and requires specific plan and auth scopes. This is exactly the cost/entitlement context an agent needs before invoking.

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 operation and output shape, then prerequisites and cost. Dense but nearly every clause carries information; the second sentence is long but justified by the billing and entitlement caveats.

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 still enumerates the returned script structure (hook, shot/text beats, soft CTA, audio, caption) plus platform targets, cost model, and plan/auth requirements. An agent has everything needed to decide and call 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 all three parameters are already documented in-schema, including the creative_id vs Meta ad_id distinction and the app_id placeholder behavior. The description adds the framing that only format is borrowed, but no additional per-parameter syntax or format detail, 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?

States a specific verb and artifact: adapting a competitor ad's FORMAT into an organic TikTok/Reels script with named components (hook, beats, soft CTA, audio, caption). The parenthetical '(not its claims or brand)' sharply distinguishes it from ad-copying or analysis siblings like sonar_ad_spy_ad_analysis.

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?

Clearly frames the use case (turn a proven ad format into a filmable organic script) and adds preconditions: Indie/Agency plan or trial, and an authorized Sonar account or write-scope API key. It does not name a specific alternative tool or say when NOT to use it versus sonar_ad_spy_analyze_ad.

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 flag a non-readonly, open-world, non-idempotent call, and the description corroborates with "WRITE tool". It adds genuinely useful context the annotations cannot carry: it spends one of the account's daily Ad Spy lookups, same-day re-opens are free, over-allowance calls return a cached copy flagged with meta.stale and a meta.note to relay, and an Indie/Agency plan plus write-scoped auth is required.

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 dense sentences, each carrying distinct information (purpose, routing, cost/auth), with the tool's own verb and resource front-loaded. The quota and plan constraints are packed into one long clause, which is slightly heavy but not 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?

No output schema exists, and the description compensates by naming the relevant response fields (allowance, meta.stale, meta.note) and the auth/plan prerequisites. For a single-parameter search tool, nothing needed to call it correctly 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?

Only one parameter and the schema already documents it at 100% coverage with an example ("Brand or company name, e.g. \"duolingo\""). The description's "free-text search ... by brand or company name" restates the schema rather than adding syntax, normalization, or matching-behavior detail, so the high-coverage 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 and resource ("free-text search for Facebook advertiser pages") plus the qualifying scope "by brand or company name, not tied to a tracked competitor", which separates it from competitor-bound siblings like sonar_ad_spy_scan or sonar_ad_spy_competitors.

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?

Names the two concrete follow-up paths and their conditions: open a result with sonar_ad_spy_open_page, or attach it to a competitor with sonar_ad_spy_link. It also states the quota consequence of calling, which is the main decision factor versus other discovery 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?

Beyond the readOnly/idempotent annotations it discloses non-obvious traits: results are cached (so potentially stale), newer data requires a separate refresh call, `cover_url` expires while `url` is permanent, and access is gated to Indie/Agency plans. It also defines the derived `breakout` flag (≥3× the account's median views), which is behavioral meaning an agent could not infer from 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 what is returned, then the compact/full trade-off, then freshness and plan gating. Dense and mostly waste-free, though the parenthetical counter list and the `breakout` definition make the first sentence long.

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 well: field list, the breakout flag, and the compact/full difference including which URL is durable. It covers caching, refresh, and plan gating. What it omits is pagination/truncation behavior beyond `limit` and the shape of the response envelope.

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 already 100%, so baseline is 3. The description still adds value by explaining the consequence of `fields`: compact omits the expiring `cover_url` but keeps the permanent `url`, caption, dates and all counters. It does not discuss `sort` or `limit` beyond the schema, so it earns only a modest lift over 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?

Opens with a precise verb+resource+scope: 'A linked TikTok account's cached public videos with real counters (views, likes, comments, shares, saves), caption, post date and a `breakout` flag'. It names the sibling that does the adjacent job (sonar_ad_spy_refresh) and clarifies the cached-vs-live distinction, so an agent can separate it from refresh without reading 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?

Gives explicit routing advice: 'Cached read; sonar_ad_spy_refresh with kind "tiktok" fetches newer videos', which tells the agent when to pick the alternative. It also states the plan prerequisite (Indie/Agency, trial counts). It stops short of saying when NOT to use this tool at all (e.g. for non-TikTok platforms or unlinked accounts), so it is strong 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 destructiveHint=true and idempotentHint=true, yet the description still adds non-obvious behavioral facts: the link is shared across Sonar accounts and unlinking affects other accounts tracking that competitor, plus plan eligibility (Indie/Agency, trial counts) and the required write scope. These are exactly the consequences an agent cannot infer from structured fields.

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, no filler: mode first, action second, constraint third, side effect and prerequisites last. Every clause carries information an agent needs (write mode, target, exclusivity, blast radius, plan/auth).

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 three-parameter mutation with no output schema, the description covers purpose, exclusivity, side effects and prerequisites. It does not say what happens on a no-op (link not present, only implied by idempotentHint) or what the call returns, which would complete the picture for an agent handling errors.

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 three parameters and their formats. The one thing the description adds — that advertiser_id and account_id are mutually exclusive ('Pass exactly one') — is genuinely valuable because the schema itself does not express a oneOf constraint, but that is the only added semantic, so the baseline-3 level fits.

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 first sentence names a specific verb (remove/unlink) and a specific resource (competitor → Facebook page advertiser_id or TikTok account link), and the title plus the 'WRITE tool' prefix make the direction of the operation unambiguous. It is clearly the inverse of the sibling sonar_ad_spy_link, so an agent can select it 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 states the triggering condition clearly ('remove a wrong ... link') and gives the hard operational rule 'Pass exactly one', which is the main way to misuse this tool. It stops short of explicitly naming sonar_ad_spy_link as the tool to use for creating a link, so the routing guidance is implied rather than spelled out.

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 annotations, the description discloses that saved details are frozen at save time, lists possible status values, describes included notes/media, explains vault limit usage, and flags that media URLs are private and API-key-gated. These are meaningful behavioral and access constraints that an agent would not know from annotations alone.

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: it first identifies the vault contents and ordering, then adds privacy context and plan requirements. Every sentence carries useful 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 zero-parameter, read-only tool with no output schema, the description is complete enough to tell an agent what is returned, how it is ordered, what statuses exist, and what access limitations apply. No critical calling information 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 tool has zero parameters, so there are no parameter semantics to document and the baseline is 4. The description does not need to compensate for an input schema, and it appropriately focuses on output content and access constraints instead.

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 and scope: the account's saved ads in the vault, returned newest first, with frozen details, statuses, notes, media files, and plan usage. It distinguishes itself from sibling vault operations like save/remove/update by describing the stored vault contents rather than a mutation action.

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 prerequisites — an Indie or Agency plan, with trials counting — and warns that asset URLs require the account’s API key and must not be shared publicly. It does not explicitly name when to use this instead of vault_save, vault_remove, or vault_update, but the viewing context is clear from 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 destructiveHint=true and idempotentHint=true, yet the description adds genuinely new context: that stored media files are also destroyed, that an Indie or Agency plan (trial included) is required, and that the caller needs an authorized account or an API key with write scope. It stops short of stating reversibility or cascade effects on linked references.

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, both load-bearing, with the "WRITE tool" marker and the destructive scope front-loaded ahead of the prerequisite details. No redundant or filler language.

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 one-parameter destructive tool with no output schema, the definition covers what is destroyed and what access is required, which is what an agent needs before calling. It omits whether the removal can be undone or what the response confirms, 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 coverage is 100% and the single item_id parameter is fully documented in the schema, so the description need not restate it. The description adds nothing about the identifier's format or sourcing, which is correct at baseline for one well-documented parameter.

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 ("delete") and resource ("a saved ad and its stored media files from the vault"), which separates it from sonar_ad_spy_vault_save and sonar_ad_spy_vault_update. It does not explicitly name those siblings, 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?

Usage is implied by the delete verb and the plan/auth prerequisites, but there is no explicit guidance on when to remove versus update or hide an ad, and no named alternative tool. It gives prerequisites rather than selection 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?

The description goes far beyond the provided annotations by detailing internal operational behaviors. It explains that media is downloaded and details specific logic regarding expired links—they are refetched once, which incurs a specific cost ('one Ad Spy lookup').

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 definition is highly dense but maximizes information density; every sentence conveys critical operational detail. It avoids unnecessary jargon while clearly laying out constraints and consequences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of a vault-saving mechanism, this is extremely complete. It covers authentication needs, storage limits, state management (polling), and resource costs, leaving no ambiguity 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?

Since the schema description coverage is 100%, the baseline score is 3. However, the description adds useful semantic context by clarifying that 'creative_ids' refers to the internal Sonar ID, not the external Meta Ad ID, which is a vital distinction.

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 the specific term 'save Meta ads to the account's private vault,' clearly identifying the action and the resource. It distinguishes this function from other related functions by focusing on the persistence and freezing of the ad details and media within Sonar's storage.

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 comprehensive usage guidelines, including plan requirements (Indie or Agency), necessary permissions (authorized account/API key), and operational flow. Crucially, it outlines the limitation behavior, reporting 'over_limit,' and instructs the user to poll 'sonar_ad_spy_vault' for status.

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 a non-read-only, idempotent, non-destructive, closed-world mutation, so the "WRITE tool" label adds little. The genuine additions are the plan gate (Indie/Agency, trial counts) and the write-scope auth requirement, which are valuable; missing is behavior on failure, whether retry is only valid for failed/partial items, and any rate limits.

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: the action first, prerequisites second. No filler, though the em-dash and parenthetical phrasing is slightly dense; it could front-load the item scope more explicitly.

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 3-parameter, fully documented mutation with no output schema, the description covers action, plan tier, and auth scope adequately. It leaves out error/not-found behavior and whether a successful call returns the updated item, which are minor given the small surface.

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 each parameter already carries its own description, including 'null clears it' and what `retry` re-queues. The description's 'set or clear' and 'retry its media download' restate the schema rather than adding format or edge-case detail, 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?

The description uses a specific verb phrase and resource: sets or clears a saved ad's note and re-queues its media download. That is clearly distinguishable from sibling mutators like sonar_ad_spy_vault_save and sonar_ad_spy_vault_remove by effect, even though it doesn't name them.

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 states the two supported actions (edit note, retry download) and the plan/auth prerequisites, which implies when to reach for it. However, it never tells the agent when NOT to use it or which sibling to pick instead (e.g., vault_save for a new item, update_keyword_note for keyword notes).

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, but the description adds substantial behavioral context: newest-first ordering, parity with the in-app Recent Alerts panel and email digest, type-specific payloads, dependency on enabled alert rules, daily detection cadence, and the Indie-plan requirement. 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 dense but efficient: it front-loads what the feed is and its ordering, then covers prerequisites, cadence, and polling behavior. Each clause carries operational information, with no filler or redundant restatement of the title.

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?

Even without an output schema, the description gives the agent enough to call the tool correctly: event categories, payload contents, the dependency on enabled rules, daily detection, and plan requirements. It could be slightly more complete by mentioning event identifiers or how to paginate beyond `limit`, but those are minor for a read-only feed.

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 value beyond the schema by prescribing `since` for polling use, tying `type` to the alert rules the user has enabled, and indicating that payloads vary by event type. It does not discuss `limit` or `app_id`, but the schema already documents those fully.

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 tool as a feed of detected alert events for the workspace, newest first, and enumerates the event types. It also indirectly distinguishes itself from rule-management tools by noting events only exist for alert types enabled via sonar_set_alert. However, it lacks an explicit verb like 'list' or 'get' and does not directly contrast with the sibling sonar_list_alerts.

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 operational guidance: poll with `since` to react programmatically, and expect detection to run once daily. It also states the prerequisite that alert rules must be enabled. It does not explicitly say when to prefer this over list_alerts/delete_alert, so it stops short of full when-not 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 cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=false), and the description goes well beyond them: it discloses a 7-day per-app rate limit with the exact 429 cooldown behavior, and the authorization requirements (paid non-trial Indie plan, authorized account or API key with write scope). That is the kind of operational context an agent cannot infer from structured fields.

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 critical "WRITE tool" signal, then capabilities, then constraints, then auth — a sensible priority order with no filler sentences. The middle capability clause is a dense multi-item run-on, but every clause carries distinct information, so the density is defensible rather than 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?

With no output schema, the description carries the burden of describing returns, and it does so concretely (named opportunity themes with why-now narrative and per-keyword metrics, threat narratives, diff vs previous). Combined with rate-limit and auth disclosure, an agent has everything needed to call this 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?

Only one parameter, and schema description coverage is 100% — the schema already spells out "Sonar app UUID of YOUR OWN tracked app to analyze. NOT a store id, NOT a competitor id." The description's "one of your own apps" reinforces the ownership constraint but adds no format or sourcing detail 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?

States a specific verb and resource ("generates a fresh AI competitive insight for one of your own apps") and enumerates the three concrete artifacts it produces: opportunity themes, threat narratives, and a diff against the prior analysis. This is clearly distinguishable from read-oriented siblings like sonar_competitor_landscape or sonar_competitor_keywords.

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-not condition ("At most one analysis per app per 7 days") including the failure mode (429 with next available time) and names the alternative for reading the existing result ("use sonar_competitor_landscape to read the current one"). It also states the plan and auth prerequisites that gate invocation.

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 (readOnlyHint, idempotentHint, non-destructive, openWorld), so the bar is lower. The description adds genuinely new behavioral context: it discloses the return shape (overall score plus itemized checks) and an operational constraint (free tier with limited daily use per IP). That rate-limit disclosure is exactly the kind of detail annotations cannot express.

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 verb and return value, then the improvement use case, then the operational caveat. Nothing is wasted, though the trailing 'etc.' is slightly loose and the return-value sentence could be tighter.

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 usefully explains what comes back (score + itemized breakdown). Rate limits and no-API-key operation are covered, and the required inputs are handled by the schema. Missing only guidance on failure modes or how the breakdown is structured, which 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%, so the schema already documents store, country, and store_id in detail (including enum values and storeId cross-reference to sonar_app_search). The description adds no parameter-level meaning beyond 'for an app', 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 and resource: 'Calculate an ASO (App Store Optimization) audit score (0-100) for an app.' The purpose is unambiguous and none of the sibling tools (keyword, screenshot, rankings, revenue) do the same thing, so an agent can route to it without confusion.

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 usage ('so you can identify what to improve') and notes it works without an API key, but never states when to prefer this over adjacent tools like sonar_app_overview, sonar_app_extract_keywords, or sonar_analyze_competitors, nor any prerequisites. Usage context is implied rather than prescribed.

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 ordering ('newest first'), a plan gate ('Requires an Indie plan (trial counts)'), and which fields each specialized change type carries. It omits pagination/continuation behavior, which is the only notable 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?

Single dense paragraph, front-loaded with the resource and scope, and the ordering rule and use case land before the parenthetical detail. The long parenthetical enumeration of change types is information-dense but earns its place; slightly heavy for one sentence.

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 return-value burden — it discloses ordering and the fields for the two specialized types, plus the plan requirement. It could say more about the shape/fields of the common change records, but what an agent needs to call the tool correctly is present.

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% with an enum and default documented, so baseline is 3. The description goes further by explaining what the `header` and `in_app_event` enum values actually yield (action added/changed/removed plus artwork; title, kind, dates), which the schema does not.

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 (change history for a tracked app) and enumerates the exact change classes it returns: releases, metadata edits, screenshot swaps, price changes, category moves, header swaps, and iOS In-App Events. An agent can distinguish this from sibling tools like sonar_app_overview or sonar_alert_events purely from the description.

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 a concrete use case — 'correlating rank movements with what the app (or a competitor) changed' — which implies when to reach for it. It also names the `type` filter's role ('omit for all types') and the plan prerequisite. It stops short of naming alternatives (e.g. sonar_alert_events) or stating 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.

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

Annotations already mark this read-only, idempotent and non-destructive, but the description goes well beyond them: 403 gating on plan tier, `key_lacks_analytics`, `pending` delivery lag of 24-48h, the full set of non-ready status values with their fixes, `reported: false`/null semantics, and the warning not to read an empty series as zero. That is exactly the behavioral context an agent cannot get from 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?

Dense but front-loaded: the funnel definition comes first, then data sources, then prerequisites, then the status/error protocol. Every clause carries information, though the status enumeration is long enough that it reads as a wall of text rather than a tight structure.

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, yet the description explains what comes back (funnel metrics, conversion rates, source breakdown, daily series, status/message, reported flags) and how to interpret gaps. For a complex, connection-gated analytics tool, the agent has everything needed to call it and to avoid misreading results.

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 (including the `store` enum and window semantics) are already documented in the schema. The description reinforces the ASC-definition subtlety (impressions include product page views) and the Sales-report provenance of downloads, but adds little per-parameter meaning 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 (App Store Connect App Analytics funnel for one of your own iOS apps) and enumerates exactly what it returns: impressions → page views → downloads, conversion rates, search share, sources, installs, deletions, sessions. The iOS-only framing plus 'Downloads come from the Sales report' distinguishes it from siblings like sonar_app_sales and sonar_app_revenue.

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 context for use: requires Agency plan and an ASC connection with an Admin-role key, and tells the agent to always check `status` before reading data. It does not, however, name a sibling alternative or state explicitly when to prefer sonar_app_sales / sonar_app_overview instead, so it falls 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuinely new operational context not present in structured fields: no API key required and a per-IP daily free-tier rate limit, which matters for call planning.

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 what is extracted and how it is ranked, then use case, then the constraint. Nothing is redundant with the name 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?

For a read-only extraction tool with full schema coverage, annotations covering safety, and no output schema, the description supplies what is missing (ranking, competitor relevance, free-tier limits). It could be tighter on return shape (e.g., how many keywords come back by default), but that is largely covered by the 'max' parameter.

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 all four parameters (store, store_id, country, max) are fully documented in the schema, including the store_id cross-reference to sonar_app_search. The description adds no parameter-level 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?

The description states a specific verb and resource ('Extract the most likely target keywords from an app's title and description') and adds ranking behavior. It is clear what the tool produces, though it never names or contrasts the closely related siblings (sonar_app_keywords, sonar_competitor_keywords, sonar_keyword_suggestions), so an agent must infer the distinction from the inputs alone.

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 understanding what an app (yours or a competitor) is optimizing for' implies the use case and adds the free-tier constraint, but there is no explicit when-to-use vs. when-not, and no alternative tool is named despite several keyword-oriented siblings existing.

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, so the bar is low, and the description clears it comfortably: it discloses cursor pagination with a default page size of 50, the Indie-plan requirement, and the provenance semantics of `popularity` (apple vs proxy, floored Apple readings, null on Android). That is non-obvious behavioral context an agent cannot get from the schema or 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-loads purpose and return fields before the domain detail, with no filler sentences. The popularity paragraph is dense and long, but each sentence carries semantics an agent would otherwise misread, so it earns its space even if it could be broken into shorter clauses.

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 work of explaining the returned record shape (difficulty, popularity variants, results count, note, starred_at, ids), plus pagination and plan gating. An agent can call this correctly and interpret the response without further reference.

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, but the description adds a detail absent from the schema: the concrete default page size of 50 (the schema only says 'server default applies'). It also clarifies that `keyword_ids` and tracked-keyword ids come back from this call, which frames how pagination params are used.

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 tracked keywords for an app) and enumerates the returned fields, so the scope is unambiguous. It never explicitly contrasts itself with the keyword-related siblings (sonar_keyword_metrics, sonar_competitor_keywords, sonar_discovered_keywords), so sibling differentiation is only indirect via the downstream-id mentions.

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 description tells you the ids feed sonar_update_keyword_note, sonar_star_keyword, and sonar_keyword_rankings, which helps an agent place the tool in a workflow. It gives no explicit when-to-use/when-not versus the other keyword-listing tools, though it does add the practical prerequisite that an Indie plan is required.

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 the description adds materially new behavior: free-tier daily limits per IP, and a throttling fallback that returns Sonar's stored copy as `{ data, meta }` with `meta.stale: true`, `meta.stale_as_of`, and a `meta.note` to relay to the user. That is exactly the kind of operational detail annotations cannot carry.

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: what it does and returns, the auth/rate-limit profile, then the stale-data contract. Front-loaded with the core action, 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?

There is no output schema, and the description compensates by naming the returned fields and the alternate `{ data, meta }` stale shape. Combined with the free-tier caveat, an agent has everything needed to call it and interpret the result.

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 store/country/store_id formats are fully documented in the schema. The description adds only the notion of a 'store ID' and the Android-vs-iOS metadata nuance, 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?

States a specific verb and resource ('Look up a single app by its store ID') and enumerates what comes back (name, developer, category, rating, reviews, installs, price). This clearly separates it from the search-oriented sibling sonar_app_search, which returns many apps rather than one.

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?

Establishes the usage context: single-app lookup keyed by store ID, usable without an API key on the free tier. It also cross-references the workflow ('the storeId returned by sonar_app_search works as-is'). It stops short of explicitly excluding or routing against the near-sibling sonar_get_app, so it is strong context without full when-not 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new context: it is a computed, rank-history-derived read ('already computed from rank history') and it carries a plan precondition ('Requires an Indie plan (trial counts)'). It does not describe rate limits or response shape, keeping it below 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?

Purpose is front-loaded before the metric enumeration, and every listed element serves to convey scope. The single dense run-on sentence is long and could be segmented, but it avoids filler and does not pad beyond useful 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 no output schema, the description usefully enumerates the return contents, which an agent needs. Combined with the plan precondition and the when-to-use cue, an agent has enough to call it correctly. Response types/units and any pagination behavior remain unstated, keeping it from a 5.

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 (app_id with its UUID/not-a-store-id note, and the days 7-90 window) are already fully documented. The description mentions 7-day deltas and improvements, echoing but not extending the days parameter. With the schema doing the heavy lifting, 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 and resource: the dashboard's computed scoreboard for one app, delivered in a single call, and enumerates the exact contents (visibility index, share of voice, keyword counts, improvements/drops, opportunity list). This makes the tool's scope unambiguous. It stops short of naming a sibling (e.g., sonar_app_aso_score or sonar_app_rankings) it differs from, so it does not fully reach the sibling-differentiation bar for 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?

Provides a clear trigger: 'Use it when asked how an app is doing.' That gives an agent a concrete context for selection. It does not, however, name alternatives or say when NOT to use it (e.g., versus raw rank or keyword tools), so it is a strong 4 rather than 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description still adds substantial behavior: compact-by-default output shape, a roughly 7x size difference for `full`, cursor pagination at 50 keywords per page, plan gating, and explicit interpretive rules (null ≠ not ranked, absent rank ≠ collection failure, legacy history holds positive ranks only). Those warning-level semantics go well beyond anything in 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 purpose, then output shape, then semantics, then usage and constraints — a sensible order with no filler sentences. It is dense and somewhat long, and the rank/unranked/null encoding is explained in the body in a way that duplicates the `fields` schema text, but nothing is purely decorative.

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 and six parameters, the description carries the return-value burden and discharges it well: default shape, alternate shape, pagination, and ambiguity rules are all covered. It stops short of stating the response envelope (next_cursor handling, total counts) or behavior when the app has no tracked keywords.

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 `fields` enum already documents compact vs full, the `ranks` list encoding, positions_gained sign convention, and the observations statuses in comparable detail. The description largely restates that material, adding only the pagination default of 50 per page and the implicit cue that `full` is for day-by-day observation grids.

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-plus-resource statement: rank history for an app's tracked keywords over a requested window. The app-scoped framing implicitly separates it from sonar_keyword_rankings, but it never names that sibling explicitly, so the differentiation is inferred rather than stated.

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 to check how rankings moved after a metadata change or to find keywords trending up or down" gives concrete decision context, and "Requires an Indie plan (trial counts)" is a useful prerequisite. There is no explicit when-not guidance or named alternative (e.g., sonar_keyword_rankings or sonar_app_keywords).

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 and open-world, and the description layers on real operational context: an API key or connected account is required, billing is 1 credit per call, and it is excluded from the free tier. It also discloses accuracy limits per storefront (never above medium for review-derived iOS installs) and enumerates the returned fields, which annotations cannot express.

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 purpose and the return-field list are front-loaded, then the store-specific caveats follow in a logical order. The single dense paragraph is slightly heavy, and the `source` values are mentioned twice, but no sentence is filler given the absence of an output 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 carries the full burden of explaining return values, and it does so field by field (`monthly_range`, `installs` with estimate/low/high/source, confidence grade with factors, methodology). Combined with auth, cost, and per-store accuracy caveats, an agent has everything needed to call it and interpret the result responsibly.

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 goes further by explaining why `store` matters — iOS installs come from rating counts (`source: review_derived`) while Android exposes a public count with no range. It adds nothing extra for `country` beyond the schema's own ISO-code 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?

States a specific verb and resource — "Estimate monthly revenue for an app" — plus the signals the model uses (installs, ratings, category benchmarks). The closing line "The figure is a model estimate, not reported revenue" implicitly separates it from the actual-sales sibling, so an agent can pick between them 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 strong situational guidance: on iOS the install base is derived and estimates are capped at medium confidence, so the caller is told to "quote the range rather than the point figure"; on Google Play there is no install range. It never names a specific sibling alternative (e.g. sonar_app_sales) by name, which keeps it 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial context beyond them: API-key/connected-account requirement, cost (1 credit per call, not free tier), and the throttling fallback behavior with the exact `{ data, meta }` shape, `meta.stale`, `meta.stale_as_of`, and `meta.note` to relay to the user.

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 and the four sentences are dense with distinct value (routing, filters-vs-window caveat, cost/auth, stale fallback). It is on the longer side and the throttling detail is information-heavy, but each sentence carries unique information rather than 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?

For a read-only tool with no output schema, the description covers the missing pieces an agent needs: auth/cost prerequisites, the sparse-filter caveat, and the alternate return shape under throttling. Nothing needed to call it correctly appears to be absent.

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 adds meaning beyond the schema by explaining that the star-rating filters and `limit` operate on the fetched window (up to ~500), which explains why filtered results can be sparse. It doesn't restate per-parameter syntax, appropriately leaving that to 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 and resource ("Fetch user reviews for any app") plus the source ("live from the store") and scope (~500 most recent or helpful per country). It explicitly distinguishes itself from the sibling sonar_review_insights, which returns themed AI analysis, so an agent can route correctly 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?

Gives concrete when-to-use contexts (sentiment analysis, feature-request mining, competitive research) and names the alternative for summarized data (sonar_review_insights). It also warns about a usage pitfall: a narrow filter on a small app may return few or no reviews, since filters apply to the fetched window.

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 the description goes well beyond them: plan-gating behavior (403), the connection prerequisite, the meaning of every non-`ready` status value, the warning never to read an empty series as zero, the `reported: false` null-metric convention, and the static-FX approximation caveat on proceeds_usd_approx. That is exactly the behavioral context an agent cannot get from structured fields.

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?

Dense but front-loaded: what it returns first, then constraints, then the status-handling rules. Every sentence carries operational information, though the status paragraph is long enough that a bulleted treatment would scan faster.

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 and five parameters, the description carries the full burden and does so: it describes the returned metrics and breakdown shape, the time-window semantics, the gating conditions, and how to interpret empty or partial results. Nothing an agent needs to call and correctly interpret this tool 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 app_id, start, end, days and store are all documented in the schema with patterns, defaults and ranges. The description adds no parameter-level syntax or format detail beyond confirming iOS-only data, 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 (App Store Connect sales for one of your own iOS apps) and enumerates exactly what is returned: daily first-time downloads, redownloads, IAP units, approximate proceeds, window totals, and a per-country breakdown. The scope narrowing ('iOS only', 'your own apps', 'same numbers as the Performance page') makes it distinguishable from the broader revenue/overview 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?

Gives concrete preconditions and failure routing: requires the Agency plan (403 otherwise) and an App Store Connect connection at /settings/connections, plus the instruction to check `status` before trusting data. It does not name an alternative sibling (e.g. sonar_app_revenue) for the non-App-Store-Connect case, so the when-to-use-this-instead guidance is incomplete.

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 safety (readOnly, idempotent, non-destructive), but the description adds real operational context the annotations cannot: works without an API key on a per-IP free tier, Apple search results are capped at the top 50 and cached up to 30 minutes, editorial cards are excluded, and throttling can return a stored copy surfaced as `{ data, meta }` with `meta.stale`, `meta.stale_as_of` and a note to relay to the user. That is a meaningful disclosure of degraded-state behavior beyond schema and 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 core action and the main use case in the first clause, then the return shape, then the source semantics. It is dense and long for a single paragraph, and the per-source taxonomy of `app_store` / `itunes_search` / `google_play` is verbose, but each of those details prevents a concrete reporting error, so little is genuinely 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?

There is no output schema, so the description carries the return-value burden alone — and it does: it names the `{ source, data }` envelope, the compact field set, the `rank` semantics per source, and the alternate `{ data, meta }` stale response shape. Combined with auth and freshness notes, an agent has everything needed to call this and interpret the result.

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 (query, store, num, fields, country) is already documented there, including the compact-vs-full field list. The description restates the compact default and the `fields: "full"` option without adding syntax or format detail beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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 ("Find apps in the App Store or Google Play by keyword") and immediately names its purpose in the workflow (get a store ID before calling other tools). It also distinguishes itself from sonar_app_lookup and sonar_track_keywords, so an agent can route correctly 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?

Explicit when-to-use is given (resolve keyword to store ID; one-off snapshot of a position), plus when-not-to-use alternatives: sonar_app_lookup for one app's full details, sonar_track_keywords + sonar_app_rankings/sonar_keyword_rankings for rank history, daily tracking, or positions beyond 50. It also warns which output must never be reported as a rank.

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 annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description adds genuinely useful context: this is a cancellation rather than a deletion, the reply reverts to draft rather than vanishing, and a plan plus write-scoped credential is required. It stops short of saying what happens on a non-scheduled or already-posted reply, and it does not acknowledge the non-idempotent behavior the annotations flag.

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?

One dense sentence with the operation class ('WRITE tool') front-loaded, followed by the effect, then the prerequisites. No filler and nothing buried.

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 one-parameter, no-output-schema tool, the description covers what it does, the resulting state, and the access requirements. The only real gap is edge-case behavior when the reply is not currently scheduled.

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?

There is a single parameter with 100% schema description coverage, and the schema already explains that review_id is a Sonar review id from sonar_review_inbox rather than Apple's id. The description adds no further parameter guidance, 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 gives a specific verb and resource ('cancel a scheduled reply') and even specifies the state transition ('it goes back to draft'), which cleanly separates it from sonar_post_review_reply and sonar_draft_review_reply in effect. It never explicitly names a sibling tool, so it falls just short of the top band.

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 timing condition 'before it posts' tells the agent when the tool applies, and the entry conditions (Indie plan, authorized account or write-scoped API key) are stated outright. What is missing is an explicit exclusion, e.g. what to use if the reply has already been posted, or how it differs from dismiss_review_reply.

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 annotations, it discloses plan requirements, data freshness (last 7 days), pagination defaults, gap-marking behavior, and detailed popularity-source semantics including Apple vs proxy readings. This is rich behavioral context that helps an agent 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 front-loaded with purpose and scoping, then moves logically through gap analysis, pagination, plan requirements, and popularity interpretation. The popularity section is lengthy but justified by the nuance it explains; only minor tightening would improve it.

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 covers the essential context: what is returned, freshness window, pagination, plan gating, gap analysis, and the tricky popularity fields. An agent has enough information to invoke and interpret 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 input schema already documents every parameter thoroughly. The description adds some useful meaning, notably the default page size and the gap=missing marker for own_app_id, but most parameter semantics are still carried by 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 first sentence states a specific verb and resource: keywords a tracked competitor currently ranks for, with difficulty and popularity. It also gives scope (last 7 days of SERP data) and distinguishes this from own-app keyword tools by centering on a competitor.

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 explains the main usage context: pass own_app_id to get gap analysis, and the tool requires a tracked competitor plus an Indie plan. It does not explicitly name sibling alternatives such as sonar_app_keywords or sonar_keyword_rankings, nor does it 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 readOnly/idempotent/non-destructive/non-open-world, so the safety bar is low. The description adds genuine value beyond them by disclosing the plan gating ('Requires an Indie plan (trial counts)') and the AI-insight condition ('if one was generated'), which the agent cannot infer from 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 purpose is front-loaded in the opening clause, and the parenthetical inventory of return contents is informative rather than filler. The middle sentence is long and comma-heavy, slightly taxing readability 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?

With no output schema, the description carries the return-value burden and does so thoroughly: it enumerates live stats, the top gap/threat/lead rows, and the optional AI insight. Combined with the plan requirement and the schema's app_id guidance, an agent has everything needed 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 coverage is 100% and the schema already spells out that app_id is a Sonar UUID of your own app, not a store or competitor id. The description adds nothing about the parameter, 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 concrete verb+resource: the full competitive keyword picture for one of your own apps vs every tracked competitor, and enumerates the returned stats (gaps, winnable gaps, climbers, leads). It distinguishes itself functionally ('in one call') from narrower siblings like sonar_competitor_keywords, but never names those alternatives explicitly.

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 usage context: 'Use it when choosing which keywords to target next.' This tells the agent the decision the tool supports, but gives no when-not guidance and does not point to alternative tools for related questions.

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 declare the write profile (readOnlyHint=false, non-idempotent, openWorld), and the description adds substantial non-redundant behavior: plan caps (Indie 10 / Agency 50, competitors uncapped), the 403 plan_limit failure mode, the required Indie plan, and the write-scope auth requirement. That is exactly the extra context annotations cannot carry.

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?

Dense but front-loaded: the WRITE marker and core action come first, then product definition, return value, and constraints. Every sentence carries distinct information, though the plan/auth detail makes it longer than strictly minimal.

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 mutation tool with no output schema, the description covers return values (product id and Sonar app ids), plan caps, error behavior, and auth requirements. Nothing an agent needs to call it correctly 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 coverage is 100%, so the schema already documents the apps array, store enum, country, store_id, and optional name. The description reinforces the 1-2 store-versions framing but adds no format or syntax 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?

States a specific verb+resource ('creates a product in the caller's Sonar workspace'), defines what a product is (cross-store unit of one iOS + one Android app), and distinguishes it from sibling tracking tools. An agent can immediately tell this is the creation entry point rather than a tracking or listing tool.

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 workflow context clearly — this starts tracking apps and produces the ids needed by sonar_track_keywords and sonar_track_competitor — and gives plan/auth preconditions. It does not explicitly contrast against alternatives like sonar_track_app, so it stops short of full when/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 the mutation/safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). The description adds genuinely useful context beyond that: the plan gating, the auth requirement, and that the set becomes immediately human-visible in the Screenshot Studio with studio_url returned. It does not spell out non-idempotency, but annotations cover that.

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 action, then reference routing, then side effects and prerequisites. No filler; every sentence carries distinct 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?

With no output schema, the description steps in to note the returned studio_url, and it covers plan/auth prerequisites and the input-source alternatives. Nothing an agent needs to call this mutation correctly 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 all six parameters, including the screens/template_id exclusivity and the device_size reference to sonar_screenshot_devices. The description only restates the screens-vs-template choice, adding no format or syntax 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 verb (Create) and resource (app-store screenshot set), scoped to a product, and names the two input modes (own screens layouts or built-in template). This distinguishes it from siblings like sonar_add_screenshot and sonar_update_screenshot_set 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?

Routes the agent to sonar_screenshot_layout_guide for the JSON format and template ids, and states prerequisites (Indie plan, authorized account or write-scope API key). It does not give an explicit when-not-to-use case versus sonar_add_screenshot or update_screenshot_set, so it falls 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 destructiveHint=true and idempotentHint=true, so the safety profile is partly covered. The description adds value beyond that by disclosing auth requirements (Indie plan, authorized account or API key with write scope), which an agent needs before calling. It stops short of stating irreversibility or what the deletion returns.

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 zero filler, and the critical 'WRITE tool' nature is front-loaded before the resource and prerequisites. Every clause 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 single-parameter, no-output-schema destructive tool, the description covers the operation, its scope, and the permission requirements. Remaining gaps (reversibility, response shape) are minor, and the lack of an output schema means return values need not be explained.

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 id property already explains it is the UUID returned by sonar_list_alerts or sonar_set_alert. The description adds no parameter-level detail, so the baseline 3 applies rather than any compensation being warranted.

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: 'delete an alert subscription in the caller's Sonar workspace.' The 'WRITE tool' prefix disambiguates it from read siblings like sonar_list_alerts, and 'delete' is clearly distinguishable from sonar_set_alert. It does not, however, explicitly name those siblings as alternatives.

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 by 'delete an alert subscription,' and the plan/write-scope prerequisites are useful context, but the description never states when to reach for this tool versus sonar_set_alert (to modify) or sonar_list_alerts (to inspect). No explicit exclusions or 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 destructiveHint=true and idempotentHint=true, and the description goes well beyond them: it enumerates exactly what is destroyed (apps, tracked keywords, discovered keywords, competitor links, screenshot sets) and, crucially, what is preserved (shared store metadata, snapshots, rank history). It also states the auth/plan requirements, which no annotation conveys.

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?

One dense paragraph that is aggressively front-loaded with the operation scope, then the delete/no-delete boundary, then the return shape, then prerequisites. Every clause carries decision-relevant information; nothing is 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?

There is no output schema, but the description compensates by naming the return object keys ({ id, deleted, untracked_apps }). Combined with the explicit preserved-vs-destroyed inventory and auth requirements, an agent has everything needed to call this correctly and reason about consequences.

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 there is a single parameter, so the schema already fully documents product_id and its provenance. The description adds nothing about parameter format or sourcing beyond what the schema field description 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?

States a specific verb (delete) and resource (product) plus the full cascade: untracking every linked app with its tracked/discovered keywords and competitor links, and deleting screenshot sets. This is enough for an agent to distinguish it from the narrower sibling tools like sonar_untrack_app or sonar_delete_screenshot_set.

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 discloses prerequisites (Indie plan, authorized account or write-scope API key) and the blast radius, which helps an agent decide whether it is safe to call. However, it never explicitly contrasts itself with siblings that partially overlap (sonar_untrack_app, sonar_delete_screenshot_set), so the when-to-use-this-vs-alternatives guidance is only implied.

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 flag destructiveHint=true and idempotentHint=true, but the description adds genuinely new behavior: the last-screen deletion guard, the plan gating (trial counts), and the auth/write-scope requirement. These are exactly the failure modes an agent needs to anticipate 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?

Three short sentences, each carrying distinct information (what it does, the at-least-one-screen rule, the plan/auth requirements), with the core action front-loaded. 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 single-parameter destructive tool with no output schema, the description covers the mutation's guard, plan prerequisite, and auth requirement. An agent has everything needed to decide 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% for the single screenshot_id parameter, so the schema fully documents it ('Screen id to delete'). The description adds no additional format or sourcing 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 and resource ('Delete one screen from a screenshot set'), and the singular 'one screen' implicitly contrasts with the sibling sonar_delete_screenshot_set, which removes the whole set. An agent can distinguish the two 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 preconditions (Indie plan, authorized Sonar account or write-scope API key) and an important usage constraint (a set must keep at least one screen, so deleting the last is rejected). It does not name alternatives or explicitly say when not to use it, but the operational context is strong.

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 destructiveHint=true and idempotentHint=true, so the safety profile is known, yet the description adds genuinely new context: the exact cascade of what gets destroyed (screens and translations), that it is irreversible, and the auth/plan requirements. This is meaningful disclosure beyond the structured fields.

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 destructive scope, then the irreversible warning, then prerequisites. Every sentence carries distinct information with no 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?

For a single-parameter destructive mutation with no output schema, the description covers everything an agent needs: what is destroyed, irreversibility, and required authorization/plan. Nothing material 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 coverage is 100% and there is only one parameter (set_id, described as 'Screenshot set id.'), so the schema carries the parameter semantics. The description adds no format, syntax, or ID-source guidance beyond it, making the baseline 3 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 (delete) and resource (screenshot set) and immediately clarifies cascade scope ('everything in it (screens, translations)'), which distinguishes it from the sibling sonar_delete_screenshot that removes a single screenshot. An agent can select it 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?

Gives clear usage context: confirm with the user before deleting work they may want, and states the plan/account prerequisites (Indie plan, authorized Sonar account or write-scope API key). It stops short of explicitly naming alternative tools (e.g., update_screenshot_set or delete_screenshot), so it is a strong 4 rather than 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 readOnlyHint=false, destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds non-obvious context the annotations cannot: the plan requirement and the auth/scope requirement. It does not say what gets destroyed beyond the pair itself, which keeps it short of a 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, front-loaded with 'WRITE tool', each carrying distinct information (what it does, which sibling replaces it, what it requires). 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?

Single required param, no output schema, rich annotations, and the description still covers the destructive-write framing, the id-source convention, the sibling alternative, and the plan/auth prerequisites. Nothing needed to invoke it correctly 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 coverage is 100% and the schema already spells out that tracked_keyword_id is the UUID returned by sonar_app_keywords and not the keyword_id. The description's mention of the same distinction therefore repeats structured data rather than adding meaning — baseline 3.

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 ('stop tracking one keyword/app pair in the caller's Sonar workspace') and explicitly names the sibling it differs from. An agent can distinguish it from sonar_untrack_keywords 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 the routing rule directly: use this for a single id, use sonar_untrack_keywords to remove several or all of an app's keywords. Also names the prerequisite (Indie plan, authorized account or write-scoped API key).

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 behavior, and the description adds real context on top: an Indie-plan prerequisite, a default status filter of "new" that hides already-tracked/hidden rows, opportunity-ranked ordering (best first), and a compact-vs-full payload default. It doesn't discuss result-size behavior or what happens when the app has no discovered rows, which keeps it below a 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?

The purpose is front-loaded in the first clause, and the popularity explanation is dense but genuinely non-obvious. However, the parenthetical restating the compact/full field lists duplicates the schema's `fields` description, and the popularity paragraph is a single sprawling sentence that could be split.

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 nine parameters, no output schema, and no nested objects, the description does the work the schema cannot: it explains what a row contains, how results are ordered, how popularity is derived when Apple's reading is floored, the default filtering, and the plan gate. An agent has everything needed to call it correctly and interpret the response.

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%, including enum definitions and defaults, so the schema carries the parameter burden. The description restates the compact/full field lists almost verbatim from the schema and adds meaning mainly for output fields (popularity, popularity_source, popularity_apple, popularity_proxy) rather than inputs, 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 names a specific resource with precise scope: keywords the discovery engine surfaced for a tracked app that aren't tracked yet, split into ranked finds, competitor gaps, and AI/autocomplete ideas. It explicitly frames itself as Sonar's "what should I track next" answer, which distinguishes it from siblings like sonar_app_keywords (already-tracked) and sonar_competitor_keywords.

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 states the use case clearly and gives the follow-up path: rows can be tracked with sonar_track_keywords by keyword text + country. It also notes the Indie plan requirement. It does not explicitly contrast with the nearest alternatives (sonar_keyword_suggestions, sonar_app_extract_keywords), so the agent must infer when those are preferable.

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=false and destructiveHint=false, and the 'WRITE tool' label is consistent with them. The description adds value annotations do not carry: the hidden side effect that this also cancels a scheduled post, plus plan and write-scope auth requirements.

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 the tool type and effect front-loaded, no filler. The parenthetical '(trial counts)' is slightly cryptic but still earns its space by clarifying plan applicability.

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 write tool with no output schema, the description covers the write nature, the side effect, and the auth/plan gates. It lacks reversibility details and routing to the sibling cancel/post/draft tools, but nothing essential to correct invocation 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?

Only one parameter and schema description coverage is 100%, so the schema already defines review_id as a Sonar review id distinct from Apple's review id. The description adds no further syntax, default, or lookup guidance, 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?

States a specific verb and resource ('mark a review as not needing a reply') and adds a secondary effect (cancels a scheduled post). It does not name the adjacent siblings (sonar_cancel_review_reply, sonar_post_review_reply, sonar_draft_review_reply), leaving a real overlap with cancel_review_reply unresolved.

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 prerequisites (Indie plan, authorized account or write-scoped API key) but no explicit when-to-use or when-not guidance. Nothing tells the agent how to choose between dismissing and cancelling a reply, even though the description itself implies the two overlap.

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 only declare the non-destructive write profile; the description adds substantial context beyond them: metered billing (monthly AI-draft allowance, then 1 credit per draft), the fact that it never posts, and the auth/plan prerequisites (Indie plan, authorized account or write-scope API key). This is exactly the extra behavior an agent needs.

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?

Opens with a 'WRITE tool' marker, then purpose, then billing, then the routing tip — every sentence carries distinct, load-bearing information with no filler. Dense but appropriately sized.

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 two-parameter mutation tool with no output schema, the description covers purpose, cost, side effects (never posts), prerequisites, and alternatives. Nothing an agent needs to invoke it correctly 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% and both parameters are documented in the schema, so baseline is 3. The description references the optional hint as 'direction for this draft' but adds no syntax or format detail beyond what the schema already states.

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 ('write a fresh AI reply draft for a review') and immediately clarifies the mechanism (app instructions + optional hint) and translation behavior. It is clearly distinguishable from the write-sibling sonar_update_review_reply, which it names.

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 routes the agent: 'agents can skip this and write the reply themselves with sonar_update_review_reply (not metered)' gives both the alternative and the reason to prefer it. Combined with 'Never posts', the when-to-use/when-not decision is fully 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 only cover the safety profile (readOnly=false, destructive=false, idempotent=false). The description adds substantial behavioral context beyond that: a 90-day cooldown with a 429 and next-available time, the minimum review threshold, and non-trial Indie plan plus write-scope authorization requirements.

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-loads the operation type ('WRITE tool'), then the outcome, then constraints. Every clause carries signal — no filler, and the alternative tool and 429 behavior are stated compactly.

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, but the description lists what the analysis contains, and it covers preconditions, rate limits, and auth. For a 2-parameter write tool with no nested objects, nothing an agent needs to invoke it correctly 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 coverage is 100%, so both parameters are already fully documented, including that app_id is a Sonar app UUID (not a store id) and country is a per-market ISO code with default 'us'. The description reinforces the country dimension but adds no syntax 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?

States a specific verb+resource: 'generates a fresh AI review analysis for a tracked app from its recent reviews', and enumerates the output (praise/complaint themes, sentiment, feature requests, trend). It explicitly names the sibling sonar_review_insights as the read counterpart, so an agent can distinguish write from read 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?

Labeled 'WRITE tool' and gives explicit routing: use sonar_review_insights to read the current one. It states preconditions (at least 5 recent reviews), the rate limit (one analysis per app+country every 90 days), and account/plan requirements, leaving little 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?

The annotations already establish this as a safe, idempotent, closed-world read, so the bar is lower; the description still adds real context beyond them by quantifying output size (~1.5 KB compact versus ~10× larger for full), capping snapshots at 7 versus 90, and disclosing an Indie plan entitlement requirement.

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 front-loaded sentences with the scope first, then the payload shape, then the mode toggle; every clause carries information. Minor clutter comes from the terse '(trial counts)' parenthetical, which is unclear without context.

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 two-parameter read tool with full schema coverage, rich annotations, and no output schema, the description covers scope, payload contents, both output modes with size tradeoffs, snapshot limits, and the plan prerequisite. Nothing an agent needs in order to invoke it correctly 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 explains app_id (a Sonar UUID, not a store id) and both fields modes in detail. The description restates the same compact/full distinction without adding syntax, defaults, or error semantics 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?

States a specific verb and resource ('Get details for one tracked app'), and defines the payload as store metadata plus daily snapshots of rating, review count, version and installs. It is not differentiated from related read tools such as sonar_app_overview or sonar_app_lookup, so an agent cannot be fully certain which to pick from the description alone.

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 a useful default-and-override pattern ('Compact by default ... pass fields: "full"'), which implies when the lighter versus heavier mode is appropriate. It does not state when to prefer this tool over sibling read tools like sonar_app_overview or sonar_app_lookup, and the Indie-plan note is presented as a constraint rather than a selection criterion.

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, and the description still adds real context: inline image data is placeholder-substituted by default, and an Indie plan is required (trial counts). It stops short of explaining pagination or response size limits, but the placeholder behavior is exactly the kind of non-obvious trait worth disclosing.

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 is returned and the default placeholder behavior. The trailing '(trial counts)' clause is slightly cryptic but not wasteful; nothing else could be cut without losing 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?

With no output schema, the description carries the burden of describing the return payload, and it does so at a useful level of abstraction (layout JSON plus locale-keyed translation overrides). The plan requirement is a genuine prerequisite an agent needs. Only minor gaps remain around response size or pagination behavior.

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's include_image_data description is more complete than the tool description, including the update-rejection consequence of placeholders. The description's mention of placeholders echoes rather than extends 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?

States a specific verb ('Fetch') and resource ('a screenshot set') and enumerates exactly what comes back: every screen's layout JSON plus per-screen translation overrides keyed by locale. This clearly distinguishes it from sonar_list_screenshot_sets, which would return summaries rather than the full payload.

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: an agent can infer this is the detail-fetch counterpart to the list tool, and the description notes an 'Indie plan' prerequisite. But it never says when to choose this over the list tool or names an alternative, leaving routing 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 carry the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: 1 credit per keyword, a 5/day free tier per IP removed by an API key, a ~30 second budget with `pending`/`retry_after_seconds` retry semantics for unfinished keywords, and what `stale`/`measured_at` mean. This is exactly the behavioral disclosure the annotations cannot provide.

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, cost, and free-tier limits are front-loaded, and the density is justified because there is no output schema and the return-field semantics must live somewhere. It is a single long run-on paragraph, though, and the popularity_source/popularity_apple/popularity_proxy clause could be tightened.

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 takes on the return-value burden and does so thoroughly: freshness timestamps, stale flag semantics, popularity range and source attribution. Combined with cost, rate limits, and lateness handling, an agent has everything needed to call it and interpret the result.

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 store, country, keyword vs keywords, and the max-25 limit; baseline is 3. The description reinforces the single-vs-bulk choice and the per-keyword credit cost but adds no new input-level semantics (the detailed field explanations concern outputs, not parameters).

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 precise statement of what is returned (difficulty + popularity) for a specific resource (a keyword, or up to 25 in bulk), and explicitly distinguishes itself from sonar_keyword_search. An agent can tell exactly what this tool produces 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?

It states the selecting condition directly ('use this when you already know which keywords you care about') and names the alternative with its own selecting condition ('use sonar_keyword_search instead when you want related keyword ideas alongside metrics'). Both when-to-use and when-not-to-use are present.

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 read-only, idempotent, non-destructive behavior, and the description adds real operational context on top: results are ordered newest first, the default response omits icon URLs to roughly halve payload size, the keyword must be tracked, and Indie plan/trial limits apply. These are the details an agent needs before deciding whether to call it or to set fields=full.

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 short sentences, front-loaded with the what and how, followed by use case and prerequisites. The nested parenthetical about compact fields is slightly dense but carries genuine information; nothing is 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 does well by naming the per-entry fields (rank, store_id, app_name, measured_at, outlier) and the ordering. The `days` window default is left entirely to the schema and the return container shape (a list of per-day entries) is only implied, so a small gap remains for a data-retrieval 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 both `days` and `fields` are fully documented structurally. The description only restates the compact-vs-full distinction already present in the `fields` schema description and never mentions the `days` history window, so it adds 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 verb and resource: "SERP history for one tracked keyword — which apps ranked in the top results on each measured day, newest first." This clearly scopes it to keyword-level competitor SERP data, implicitly separating it from app-level tools like sonar_app_rankings. It stops short of naming a sibling tool explicitly, so it lands just below the top band.

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 use case — "see who competes on a keyword and how the top spots shifted over time" — plus two hard preconditions: the keyword must be tracked in the caller's workspace, and it requires an Indie plan. What's missing is a named alternative for related questions (e.g. keyword metrics or app rankings), so there is no 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?

Beyond the annotations, the description discloses paid-credit cost, refund behavior, API key/connected-account requirements, free-tier exclusion, and expected latency. It also explains stale/pending row semantics, measurement timestamps, and popularity source quirks, which are meaningful behavioral details not covered by annotations or 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?

The description is front-loaded with purpose and return shape, then moves through usage, cost/auth, timing, and field semantics. It is long but mostly earns its length; the popularity explanation is dense though still relevant for interpreting returned values.

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 return-value burden well: row count, fields, timestamps, stale/pending states, and popularity source are all explained. Combined with full parameter schema coverage and existing annotations, an agent has enough context to call and interpret this 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 description coverage is 100%, so query, store, and country are already well documented. The description adds context about what a seed keyword produces but does not materially extend parameter-level meaning 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 and resource: research a keyword and related terms, returning up to 10 autocomplete rows with difficulty, popularity, and results count. It explicitly distinguishes this from sonar_keyword_metrics for terms the agent already knows, so the sibling boundary is clear.

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 when-to-use guidance: find keywords worth targeting, versus using sonar_keyword_metrics for known terms because that is cheaper. It also discloses prerequisites, cost, and latency, which directly affects whether an agent should call 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?

Goes well beyond the readOnly/idempotent annotations: it discloses that `priority` is always 0 on both stores, that no API key is needed with per-IP daily limits, and that throttling can yield Sonar's stored copy surfaced as `{ data, meta }` with `meta.stale`, `meta.stale_as_of`, and `meta.note`. This is genuinely useful operational context, though the free-tier limits are stated only qualitatively.

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-loads what the tool does, then layers the comparison, cost profile, and fallback behavior. Four sentences all carry information, though the throttling/meta explanation is dense and could be tightened.

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 explaining the returned ordering, the always-zero `priority` field, and the stale-fallback response shape including the note to relay to the user. An agent has what it needs to call and interpret the result.

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 each parameter (seed, store enum, country) is already documented in the schema, so the baseline is 3. The description adds no syntax or format meaning for any parameter; its field-level detail concerns output (`priority`), not inputs.

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 (get) and resource (autocomplete suggestions) plus the source (App Store / Google Play) and ordering semantics. It explicitly contrasts with sonar_keyword_search, so an agent can distinguish it from the many keyword siblings 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?

Names the alternative (sonar_keyword_search) and the selecting condition ('use when you only need term ideas without difficulty/popularity scoring'), and adds that it works without an API key under a free tier. The routing decision is fully determined.

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, so safety is covered. The description adds real value beyond that: a plan-gating requirement (Indie plan, trial counts) and a summary of the per-rule fields returned (change type, scope, threshold, enabled state), which matters since there is no output 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?

Two tight clauses with the subject action front-loaded and no padding; the parenthetical example ('rank drops, review spikes, etc.') aids comprehension quickly. The trailing 'trial counts' note is slightly cryptic but still informative.

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 and no parameters, the description does the needed work by sketching the shape of each returned rule and stating the plan prerequisite. It stops short of noting pagination or ordering behavior, which is a minor gap for a list 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?

The tool takes zero parameters, so the baseline of 4 applies. The description correctly implies a plain enumeration returning all subscriptions with no filtering syntax to explain, matching the empty 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?

Starts with a specific verb+resource ('List your alert subscriptions') and immediately characterizes what a rule contains, distinguishing it from siblings like set_alert (creation), delete_alert, and alert_events (past events). An agent can tell what this returns 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?

Usage is implied by the verb and the plan prerequisite ('Requires an Indie plan'), which is genuinely useful gating context. However, it never states when to prefer this over sibling tools like alert_events or what to do when no subscriptions exist, so routing guidance is only partial.

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 safe read-only/idempotent profile, so the description's job is to add beyond that. It adds real context: cursor pagination with a default of 100 per page, and a plan entitlement (Indie plan, trial counts) that affects whether the call succeeds. It doesn't cover rate limits or error behavior, but that is a minor gap against rich annotation coverage.

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 core purpose and scope, then output value, then pagination and entitlement caveats. No filler; every clause 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 must explain return values, and it does (per-app latest snapshot with rating, review count, version, installs, plus UUIDs). Pagination mechanics and the plan prerequisite are covered, so an agent has everything needed to call 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 both parameters (limit, cursor) are already documented, and the description only restates the page-size default. Baseline 3 applies when the schema carries the parameter burden and the description adds no syntax or format detail beyond it.

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 the apps tracked in the caller's Sonar workspace') plus the exact scope (own apps + competitors) and the payload returned (latest snapshot fields). An agent can distinguish this from sonar_list_products and the many app_* tools 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?

The clause naming downstream tools (sonar_get_app, sonar_app_keywords, sonar_app_rankings, sonar_app_changes) effectively signals this is the entry point that yields needed UUIDs. It does not, however, state when to prefer this over sibling listers like sonar_list_products or sonar_app_search, so it stops short of explicit 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds non-obvious behavior on top: the result is returned in full with no pagination, and the tool is gated behind an Indie plan (trial counts). Those two facts materially affect how an agent calls and budgets for this tool, which is exactly the value-add expected beyond 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 purpose is front-loaded in the first clause and every clause carries information (return fields, id consumers, alternative tool, plan gate). It is, however, one very dense sentence with stacked parenthetical lists, which is slightly harder to scan than a two-sentence split would be.

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 compensates by naming the returned fields, and it covers the entitlement prerequisite and the unpaginated behavior. Nothing an agent needs to invoke this correctly 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 tool takes zero parameters, so per the rubric the baseline is 4, not 5. The description correctly implies there is no filtering or paging syntax to supply; nothing further is expected here.

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 every product in your workspace') and immediately scopes it as unpaginated while enumerating the returned fields (id, name, country, competitor count, store versions). It explicitly distinguishes itself from the closest sibling, sonar_list_apps, so an agent can route correctly 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?

Names the exact downstream tools that consume the returned product ids (sonar_track_app, sonar_track_competitor, sonar_remove_competitor, sonar_delete_product, screenshot-set tools) and names the alternative for per-app/competitor data (sonar_list_apps). It also states the plan prerequisite ('Requires an Indie plan (trial counts)').

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, so safety is covered. The description still adds value beyond them: it discloses that only metadata is returned (not layouts) and imposes a plan-level authorization requirement ('Requires an Indie plan (trial counts)'), which annotations cannot express. It stops short of describing ordering or pagination.

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 action and payload scope, then routing, then the plan prerequisite. Every sentence carries distinct information and none is redundant with the title.

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 takes on the return-value burden and does name the four metadata fields returned, plus the plan prerequisite. It leaves ordering/pagination of the list unspecified, which is a minor gap for a simple one-parameter list 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?

There is a single parameter with 100% schema description coverage, and the schema already tells the agent to find product_id via sonar_list_products. The description adds no syntax, format, or sourcing detail 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 opens with a specific verb+resource ('List a product's app-store screenshot sets') and immediately scopes the payload ('metadata only: store, device size, locales, studio_url'). It also explicitly distinguishes itself from sonar_get_screenshot_set, so the agent can separate the two sibling list/get tools 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?

It states the condition that routes to the alternative ('Use sonar_get_screenshot_set for full layouts') and adds a prerequisite ('Requires an Indie plan (trial counts)'). Both when-to-use and the plan constraint are explicit rather than inferred.

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 genuinely useful context beyond that: the Agency-plan requirement with a concrete 403 failure mode and parity with the /portfolio page, which helps an agent predict both eligibility and 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?

Front-loaded with the core value proposition, then a parenthetical inventory of what is returned. The enumeration is dense but each item earns its place as return-value disclosure; no filler sentences.

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 parameters and no output schema, the description carries the burden of describing the return contents, which it does thoroughly (KPIs, totals, movers, triage, opportunities), and it also states the plan prerequisite. Nothing an agent needs to decide or call correctly 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 tool takes zero parameters and the input schema is empty, so there is nothing for the description to disambiguate. Baseline for a no-parameter tool is 4.

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 ('The whole portfolio's health in one call') and enumerates the aggregation content: per-app KPIs, org-wide totals, keyword movers, triage list, and discovered-keyword opportunities. It is clearly differentiated from per-app siblings like sonar_app_overview by operating across the entire portfolio.

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 a clear usage context ('for orgs managing many apps') and a hard gate ('Requires an Agency plan (403 on other plans)'). It does not explicitly name the sibling alternatives an agent should prefer for single-app or per-metric queries, so it stops short of full when/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?

The description is unusually rich about real behavior: overwrite semantics (Apple keeps one reply per review and marks it edited), the ~24h publication lag with pending_publish→published status, and auth/plan prerequisites. However, explicitly stating that it 'Overwrites an existing response' is a non-additive update, which conflicts with the declared destructiveHint=false. That inconsistency undercuts the otherwise strong disclosure.

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-loads the action class and public consequence before operational details, and every clause (overwrite behavior, latency, auth, plan) earns its place. Dense but zero 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 3-parameter write tool with no output schema, the description covers everything an agent needs to act correctly: confirmation of public side effect, timing, expected status transitions, and permission/plan prerequisites.

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 already explains that review_id is Sonar's id (not Apple's), that body replaces the draft text, and that delay_minutes schedules posting. The description only echoes the now-vs-delayed timing, adding little beyond the schema, so the high-coverage baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.