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 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 readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds non-annotation context the agent actually needs: cursor pagination with a default of 50 per page and an Indie plan requirement (trial counts), plus the ID-passing contract. This is more than the annotations supply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, all front-loaded with the purpose first, then the output contract, then pagination and plan constraints. Every sentence carries information; only the enumeration of return fields is slightly dense but remains useful for tool selection.

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 must convey the return shape, and it does name the key fields and the ID families that downstream tools consume. Plan gating and pagination are also stated. What is missing is any indication of what to do when the app has no tracked keywords (empty result) or ordering of 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 coverage is 100%, and the schema already documents limit (range, server default), app_id (UUID source and the 'NOT a store id' warning) and cursor (from next_cursor). The description's mention of 'default 50 per page' is the one detail that goes beyond the schema, which does not state the default value. Baseline 3 applies when the schema carries the parameter detail.

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

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List the keywords tracked for an app in the caller's Sonar workspace') and enumerates the fields returned (difficulty, popularity, results count, note, starred_at). It is distinguishable from sonar_competitor_keywords, sonar_discovered_keywords and sonar_keyword_search, though it never explicitly names 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?

It clarifies which identifier family to pass (tracked-keyword ids for note/star tools vs keyword_ids for rankings), which is genuinely useful routing context. However, there is no explicit when-to-use vs when-not-to-use guidance, and the siblings that also return keywords (sonar_competitor_keywords, sonar_discovered_keywords, sonar_keyword_search) are not contrasted.

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?

Beyond the readOnlyHint/idempotentHint annotations, the description explains rank status semantics (ranked, not_found, not_observed), warns against interpreting missing ranks as collection failures, describes cursor pagination over keywords, and notes the Indie plan requirement. This is substantial behavioral context that directly prevents misuse.

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 well organized: result shape first, then status semantics, then use cases, pagination, and plan requirement. Every sentence adds value, and the most critical caveats are front-loaded.

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

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

Given there is no output schema, the description compensates by explaining the history-array shape, all observable rank statuses, legacy gaps, pagination behavior, and plan requirements. An agent has enough context to invoke the tool correctly and interpret its responses without additional guessing.

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 useful extra meaning by specifying statuses tied to results_count, the legacy positive-ranks-only array, and the default page size of 50, which enriches the semantics of limit and cursor beyond the raw schema.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the resource (rank history for an app's tracked keywords) and the exact return shape (daily ranks over a window, one history array per keyword). It is specific and distinct from sibling tools like sonar_keyword_rankings or sonar_app_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?

The description gives concrete use cases: checking ranking movement after a metadata change or finding trending keywords. It does not explicitly name alternative tools or when-not-to-use conditions, but the context is clear enough for an agent to decide when this tool fits.

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 goes further by disclosing billing (1 credit per call on prepaid credits), auth requirements (Sonar API key or connected account), and free-tier exclusion. It also flags the epistemic caveat that the number is modeled, which is exactly the kind of context 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?

Front-loaded with purpose and outputs, then caveat, then prerequisites. Four sentences are all relevant, though 'the confidence grade is the part that says how far to trust it' mildly restates the prior sentence's description of the confidence grade.

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 and does so: it names the dollar estimate, the confidence grade (high/medium/low) plus its factors, and the methodology. Combined with schema-documented params and annotation-covered safety, an agent has everything needed to call and interpret this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%: store enum, country default/format, and the iOS/Android store_id distinction are all fully documented in the schema, including a cross-reference to sonar_app_search's storeId. The description adds no parameter-level 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 ('Estimate monthly revenue for an app') and names the inputs driving the estimate (install counts, ratings, category benchmarks). It also distinguishes itself from reported-revenue siblings like sonar_app_sales by clarifying 'The figure is a model estimate, not reported 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?

The 'model estimate, not reported revenue' caveat implies when this is the appropriate tool versus a reported-sales source, but no sibling (e.g. sonar_app_sales) is named and there is no explicit when-to-use/when-not guidance. Auth and credit prerequisites are stated, which helps callers decide eligibility but not tool choice.

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 (readOnlyHint, idempotentHint, destructiveHint) and open-world access, and the description goes well beyond them: free tier without an API key, per-IP daily limits, a throttling fallback that returns stored data shaped as { data, meta } with meta.stale/stale_as_of, and a directive to pass meta.note to the user. This is exactly the operational context structured fields cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Long for a search tool but front-loaded with purpose first, then the ranking caveat, then alternatives, then operational notes. Every sentence carries distinct, decision-relevant information with 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?

Despite having no output schema, the description explains what comes back, how to interpret iOS ordering, and the degraded throttled response shape. Combined with ratings independent of rank order, an agent has everything needed to call and correctly report 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 four parameters (query, store, num, country) are already fully documented, including enum, defaults, and range. The description adds the return metadata fields (name, developer, icon, rating) but no additional parameter meaning, so the baseline 3 is correct.

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

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (search/find) and resource (apps in App Store / Google Play) and names the concrete use case of obtaining a store ID before calling other tools. It explicitly distinguishes itself from the ranking tools, so an agent can tell it apart from sonar_app_rankings and sonar_top_charts 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?

Gives an explicit when-to-use (get an app's store ID), an explicit when-NOT-to-use (never treat list position as rank), and names the alternatives to use instead (sonar_track_keywords, sonar_app_rankings, sonar_keyword_rankings). This is about as complete a routing instruction as a search tool can carry.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new operational context: a 7-day SERP freshness window, cursor pagination with a default page size of 50, and an Indie-plan requirement with trial counting. It stops short of explaining ordering or how the gap marker affects result filtering.

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 the tool returns before moving to the gap-analysis option and then pagination/plan constraints. Dense but every clause carries information; only the parenthetical plan note feels slightly appended.

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 correctly carries the return-value burden (per-keyword difficulty and popularity, plus optional own-app rank and gap markers) and notes pagination and the plan gate. The one gap is not clarifying what 'tracked' implies upstream (a sonar_track_competitor dependency), though the schema covers the ID source.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: the literal gap marker value ('gap=missing') and the concrete default page size of 50. The cursor/limit mechanics add nothing beyond the schema, leaving this just above 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?

States a precise verb+resource: keywords a tracked competitor currently ranks for, scoped to the last 7 days of SERP data, with the returned metrics named (difficulty, popularity). That framing clearly separates it from own-app siblings like sonar_app_keywords or sonar_app_rankings without needing to open 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?

It gives a conditional usage pattern ('Pass own_app_id for gap analysis') and states the plan prerequisite, which is real guidance, but it never names an alternative tool or an explicit when-not-to-use condition. Usage is implied by the competitor-scoping rather than routed against siblings.

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 declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds meaningful extras beyond that: the Indie-plan access requirement, that the default status is still-actionable 'new' rows, and the reason rows appear here (not yet tracked). It stops short of rate limits or pagination behavior.

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 core purpose leads, then the row taxonomy and metrics, then the track-next framing and plan note. Every clause carries information, though the em-dash-heavy construction is heavier than strictly necessary.

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 eight parameters and no output schema, the description usefully compensates by naming the returned fields (popularity, difficulty, AI relevance, opportunity score sorted best-first). Access requirements and the follow-up action are both covered, leaving only minor gaps around pagination and result volume.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3 and the schema already documents all eight parameters including the enums and ranges. The description's 'ranked finds / gap / idea' phrasing loosely mirrors the bucket enum but adds no syntax, format, or default detail the schema lacks.

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 and scope: keywords the discovery engine surfaced for a tracked app that aren't tracked yet, broken into ranked/gap/idea categories. This cleanly distinguishes it from sibling keyword tools like sonar_app_keywords (tracked keywords) and sonar_keyword_suggestions by explicitly framing the result as untracked candidates.

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?

Frames itself as 'Sonar's what-should-I-track-next answer' and routes the follow-up action to sonar_track_keywords, plus notes the Indie plan requirement. It gives clear context but does not contrast with the other keyword-discovery siblings (sonar_extract_keywords, sonar_keyword_suggestions) that an agent might otherwise pick.

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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so safety is covered. The description adds real value beyond that: it discloses the shape/volume of the return payload (up to 90 daily snapshots) and a plan gate ('Requires an Indie plan'). It does not mention rate limits or freshness of the snapshots, so it falls 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?

Two tight sentences with no filler: scope and payload first, plan constraint second. 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 takes on the burden of describing returns and does so (store metadata, daily snapshots of rating, review count, version, installs), plus the plan requirement. An agent has enough to call it correctly and anticipate the response shape.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema description already explains the app UUID versus a store id, including the sibling calls that produce it. The description adds nothing about the parameter, so the baseline 3 for high schema coverage is appropriate.

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

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Get full details for one tracked app') and scopes it to the caller's Sonar workspace, with a concrete preview of the payload (store metadata plus up to 90 daily snapshots). It does not explicitly distinguish itself from near-neighbors such as sonar_app_overview or sonar_app_lookup, so an agent must infer the difference.

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: 'one tracked app' and 'in the caller's Sonar workspace' suggest reading a single followed app, but there is no explicit when-to-use, no prerequisites for tracking first, and no naming of the alternative tools (sonar_app_overview, sonar_app_lookup, sonar_list_apps).

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 already cover the safety profile (readOnly, idempotent, non-destructive, open-world), yet the description adds real operational context beyond them: per-keyword credit billing, the unauthenticated rate cap, a ~30s compute deadline with a `pending` status that is explicitly not charged, and a retry_after_seconds recovery loop. It further discloses freshness semantics (measured_at vs popularity_measured_at, 7-day `stale` threshold), which is exactly the kind of behavior 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?

Purpose and the sibling alternative are front-loaded in the first two sentences, and the remaining content is dense, non-redundant operational detail. It runs long and the pending-state sentence carries a slightly overloaded parenthetical ("queued on Sonar's scrape fleet, not charged, results are being cached"), but no sentence is filler.

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

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

For a read-only tool with no output schema, the description compensates by naming the returned fields (measured_at, popularity_measured_at, stale), explaining their semantics and the pending/retry_after_seconds shape. Combined with the billing, auth, and rate-limit coverage, 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 description coverage is 100%, so the schema already documents store/country/keyword/keywords, including the keyword-vs-keywords mutual exclusion; that establishes a baseline of 3. The description still adds meaning the schema does not: cost scales linearly at 1 credit per element of `keywords`, and the free-tier cap effectively bounds bulk use to 5 keywords/day without auth.

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 states the exact resource and outputs ("Difficulty + popularity for a specific keyword") plus its bulk scope (up to 25), which is a precise verb+resource statement. It explicitly names the sibling it is not (sonar_keyword_search) and states the condition that separates them, 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?

Explicit when-to-use ("when you already know which keywords you care about") and an explicit alternative with its selecting condition ("Use sonar_keyword_search instead when you want related keyword ideas"). It also states cost (1 credit/keyword), auth prerequisites (works keyless to 5/day per IP; API key removes the cap), and the padding/retry path via retry_after_seconds — nothing material is left 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/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds real value beyond them: a tracking precondition, a plan gate ('Requires an Indie plan (trial counts)'), and result ordering ('newest first').

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 resource and payload, then prerequisites, in efficient prose with no filler. Four short sentences, each carrying information, though the ordering/plan sentences could be tightened slightly.

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

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

With no output schema, the description carries the burden of explaining the return value and does so ('which apps ranked in the top results on each measured day, newest first'). Prerequisites and plan gating are covered; only pagination/volume limits are unaddressed, 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 both parameters are already documented, making 3 the baseline. The description reinforces that the keyword must be tracked in the workspace, but adds no syntax or format detail the schema lacks, and says nothing specific about the days window.

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 verb and resource ('SERP history for one tracked keyword') and clarifies the payload: which apps ranked in the top results on each measured day, newest first. It is distinguishable from the per-app sibling sonar_app_rankings only by implication ('one tracked keyword'), so it stops short of explicit sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear use case ('see who competes on a keyword and how the top spots shifted over time') plus prerequisites: the keyword must be tracked in the caller's workspace and an Indie plan is required. It names no explicit alternative tool (e.g. sonar_app_rankings for a per-app view), so it lacks 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 only cover the safety profile (readOnly/idempotent/non-destructive/openWorld), but the description discloses the real behavioral burdens: cost (10 credits per call, refunds for uncomputed rows), auth requirements (Sonar API key or connected account, not free tier), latency (~30 seconds), and the `stale`/`pending` state semantics with their thresholds. This is well beyond what the structured fields convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose, return shape, and the sibling comparison are front-loaded and each subsequent sentence carries real information about credits, staleness, and pending behavior. It is dense and long for a 3-parameter tool, but nearly every clause earns its place; minor trimming of the pending/refund detail would tighten 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?

With no output schema, the description carries the full burden and does so: it enumerates the return columns, explains `measured_at`/`popularity_measured_at` as ISO 8601 UTC, defines the 7-day `stale` threshold, and explains the `pending` state. An agent has everything needed to call and interpret results correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents query, store, and country (including the 72-market constraint). The description reinforces the store/autocomplete relationship but adds no format or syntax 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?

States a specific verb+resource ("Research a keyword and related terms") and immediately defines the output: up to 10 rows, seed keyword plus top autocomplete suggestions, each with difficulty, popularity, and results count. It also explicitly distinguishes itself from sonar_keyword_metrics, so an agent can route between the two 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 explicit when-to-use guidance ("find keywords worth targeting") and names the alternative with the selecting condition ("for metrics on terms you already know, sonar_keyword_metrics is cheaper"). It further clarifies the pending/re-check handoff to sonar_keyword_metrics, 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?

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.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('publishes the reply on the App Store under the developer's name') plus the action class ('WRITE tool — PUBLIC ACTION'). An agent can immediately distinguish this from sonar_draft_review_reply or sonar_update_review_reply 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 invocation context — post now or schedule via delay_minutes, requires an Admin-role App Store Connect key, an Indie plan, and an authorized Sonar account or write-scoped API key. It stops short of naming the sibling alternatives (draft/cancel/dismiss/update reply) and when to choose them over posting.

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 by disclosing cascade semantics: the competitor link is dropped under every own app of the product, and the competitor app is untracked only if no other own app still references it. It also adds error behavior (404) and authorization/plan requirements, 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?

Three sentences, front-loaded with the WRITE marker and the core action, followed by side effects and then prerequisites. No filler; each clause 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?

For a destructive mutation with no output schema, the description covers everything an agent needs: action, cascade side effects, the untrack condition, the error case, and auth/plan requirements. Annotations and schema fill the remaining slots (idempotency, param types).

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 with UUID sourcing and an explicit warning that competitor_app_id is the app UUID, not a store id. The description adds no further parameter-level detail, 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 ('remove a competitor from a product') and immediately flags it as a WRITE tool, distinguishing it from read-oriented siblings like sonar_competitor_landscape. The scope is unambiguous: one competitor, one product, in the caller's workspace.

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 operational context — the 404 condition when the product has no such competitor, and the Indie-plan/auth prerequisites. It stops short of naming a sibling alternative (e.g., sonar_untrack_app) or stating when NOT to use it, but the trigger condition is well understood from the purpose.

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 the read-only, idempotent, non-destructive profile, and the description adds genuine extra context: a 5-minute sync cadence, newest-first ordering, per-status counts, and what 'hold reasons' (needs_human, quota, daily_cap) mean. Pagination via cursor is left to the schema, so not everything is covered, but the added behavioral value is solid.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with what the tool returns before the trailing prerequisites, and every clause carries information (reply state, translations, hold reasons, ordering, counts, next-step tool references). It is dense and slightly long, 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?

There is no output schema, so the description responsibly enumerates return fields (draft/text reply, translations, hold reasons, schedule time, live App Store response) and setup requirements. It is complete enough to call correctly, with only pagination/return-shape details left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents every parameter (limit, cursor, rating, status, country, language) precisely, including the status enum semantics. The description adds nothing parameter-specific beyond the general reply-state context, 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 (own iOS app's App Store reviews) plus a precise scope: reply state, translations, hold reasons, schedule time, live responses. The 'own iOS app' qualifier and 'synced from App Store Connect' framing distinguish it from a generic review-listing sibling.

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 setup prerequisites (Indie plan, App Store Connect connected, own iOS app) and routes the agent forward: 'Use the review `id` with sonar_update_review_reply / sonar_post_review_reply.' However, it never states when to prefer this over related review siblings (e.g., a public-review or insights tool), so the when-not guidance is implicit.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the `insight` field can be null and what to do, and the Indie plan prerequisite (trial counts). It does not cover rate limits or generation latency, keeping it at a 4.

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 purpose before the output enumeration, and the null-handling and plan note are placed last as operational details. It is dense with parenthetical lists but every clause carries distinct information, with little 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?

Although no output schema exists, the description characterizes the return payload in detail (themes, frequency, quotes, trend states, sentiment, feature requests, delta vs previous analysis) and covers the null/empty case plus the required plan. An agent has everything needed to call and interpret it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, both parameters (app_id and country) are already fully documented in the schema, including that app_id is a Sonar UUID not a store id and that country drives per-country generation. The description adds no parameter-level syntax or semantics 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?

States a specific verb and resource ('the latest AI review analysis for a tracked app') and enumerates the concrete outputs (named themes, frequency, quotes, trend movement, sentiment, feature requests). It distinguishes itself from the raw-review sibling sonar_app_reviews by emphasizing AI-generated analysis rather than review listing, so an agent can tell them apart 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?

Explicitly names the alternative (sonar_generate_review_insights) and the selecting condition (insight is null when none exists yet), plus notes the Indie plan requirement. It lacks a clear 'rely on sonar_app_reviews instead when you want raw reviews' exclusion, so it falls just short of full when/when-not coverage.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is domain behavior: settings is null until the responder is switched on, auto mode only affects reviews written after enabling and within the star range, and credit usage is included-allowance-plus-1-per-extra-draft. That is meaningful operational context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the resource and its contents, then closes with the null-state caveat and prerequisites. Dense but every clause carries information; the parenthetical about auto-mode scoping and credit pricing is load-bearing rather than 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?

With no output schema, the description usefully enumerates the return payload field-by-field, which is exactly what an agent needs to consume the result. Combined with prerequisites and the null-state rule, it covers the important edges for a single-parameter read 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% and the single app_id parameter is already documented as a Sonar UUID that is not a store id. The description reinforces the same constraint ('one of your own iOS apps') 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?

Names a specific resource (the review responder configuration) and enumerates exactly what the returned payload contains: on/off state, manual vs auto mode, instructions, sign-off, language, sync, App Store Connect status, and AI-draft usage. An agent knows precisely what it will receive. It does not explicitly contrast itself with the write sibling sonar_set_review_responder, though the 'settings' framing makes the read intent 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?

Usage is implied rather than stated: this is clearly the read surface to pair with sonar_set_review_responder, but the description never says 'use this before/after setting' or names an alternative. It does supply real prerequisites (Indie plan, App Store Connect connected, own iOS app), which partly compensates.

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=false, openWorldHint=true and destructiveHint=false, so the write/async profile is partly covered. The description goes well beyond that by disclosing the async execution model (~30s inline verification, remainder in background over hours), the exact return counts, and quota/auth constraints — exactly the kind of context annotations cannot carry. It stops short of stating what happens to previously generated keyword sets on re-scan.

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' label and the core action, then layered with returns, async behavior, and limits. Dense and largely waste-free, but delivered as a single long block where a sentence break before the quota/auth section would improve scannability.

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 specifies the return payload (generated/queued/verified_now counts) and explains why only a partial result returns inline. Combined with quota, plan, and auth requirements, an agent has everything needed to invoke this 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 description coverage is 100%, so both UUID parameters are already documented in the schema with their provenance and the 'NOT a store id' caveat. The description only implies the linkage requirement ('tracked competitor' must be linked to own_app_id), which the schema also states. Baseline 3 applies 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 — 'runs an AI keyword discovery scan on a tracked competitor' — and enumerates the concrete outputs (generated terms, SERP verification queue, inline verification, recorded ranks for both apps). The word 'tracked' plus the explicit read-path pointer to sonar_competitor_keywords cleanly separates it from siblings like sonar_track_competitor 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?

Gives explicit when-to-use context (scan a tracked competitor to discover its optimized terms), names the companion read tool, and states prerequisites: Indie plan required, authorized Sonar account or API key with write scope. It also documents the operational conditions — daily competitor limits (50 trial/Indie, 250 Agency), free re-scans of the same competitor, and reset reporting past the limit.

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 behavioral context: the Indie plan requirement (with trial counting), which materially affects whether an agent should call this. It does not add pagination or return-format detail, but the plan gate is the important addition.

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?

Essentially one dense sentence that front-loads the resource and its contents, then the routing instruction and the plan requirement. The nested parentheticals make it slightly heavy to parse, 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 compensates by describing the returned fields (canvas dimensions, store, creative-asset entries) and by disclosing the plan prerequisite. That is sufficient for a zero-parameter read tool, though it could say more about ordering/format of the returned list.

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 is 4 by rule. The description correctly implies a no-argument listing call and adds no misleading parameter claims.

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 (list device sizes for app-store screenshot sets) and enumerates what each entry contains: canvas dimensions, owning store, and the landscape App Store creative-asset category. It is clearly distinguishable from siblings like sonar_screenshot_layout_guide or sonar_get_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?

"Pick a device here before sonar_create_screenshot_set" explicitly names the downstream tool and the ordering constraint, which is strong routing guidance. It lacks a when-not-to-use clause or an alternative source for device data, so it stops short of a full 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 (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds non-obvious context: the content is static, so re-calling within a session is unnecessary, and it enumerates the reference material available.

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, zero filler. The identity of the tool and the 'one call per session' constraint are front-loaded, followed by the content inventory.

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-param, read-only reference tool with no output schema, the description is nearly complete: it identifies the artifact and lists the covered topics, and 'static text' hints at the return shape. An explicit pointer to the workflow step where it should be consulted would close the last 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?

Zero parameters, so there is no parameter semantics to explain; the baseline of 4 applies. The description correctly avoids inventing arguments for a no-arg reference tool.

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

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific resource (the layout-format reference for Sonar screenshot sets) and states exactly what it covers: layout JSON schema, coordinate system, image handling, background shapes, fonts, translation overrides, and workflow. This is clearly distinguishable from the screenshot CRUD siblings like sonar_create_screenshot_set or sonar_update_screenshot.

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 tells the agent it is static text and that 'one call per session is enough', which is real invocation guidance about call frequency. It stops short of naming alternatives or stating when in the workflow to consult it (e.g., before creating a screenshot set), so it's clear but not fully 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false) by disclosing the upsert keying, the partial-merge behavior of omitted fields (keep stored value), the plan gate, and the authorization requirement. The upsert claim sits in mild tension with idempotentHint=false, and no failure/error behavior is described, keeping this at 4 rather than 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?

Four dense sentences, front-loaded with the WRITE declaration and the core action, then keying semantics, then defaults, then prerequisites. No boilerplate or repetition; every sentence carries operational 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?

Covers the prerequisites, defaults, and upsert semantics an agent needs to call a 6-parameter mutation correctly. With no output schema, the only real gap is what the call returns (e.g., the created/updated rule identifier), which would further help an agent chain into sonar_list_alerts.

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 parameter meaning is already largely carried by the schema, and several description statements (omit threshold/scope_app_id) restate it. The genuine addition is the composite key concept — 'upserts on (type + scope)' — which ties type and scope_app_id together in a way the schema alone does not express.

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

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource+scope: 'create or update an alert subscription in the caller's Sonar workspace', and flags itself as a WRITE tool. The create/update framing cleanly separates it from sonar_list_alerts, sonar_delete_alert, and sonar_alert_events without needing to 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?

Gives clear operational context: it upserts on (type + scope), omit `threshold` for the per-type default, omit `scope_app_id` for an org-wide rule, and it requires an Indie plan plus write-scoped credentials. It stops short of explicitly naming alternative siblings or stating when *not* to use it (e.g., to modify vs. re-create), so it is strong context without full exclusion 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?

Adds substantial behavior beyond the annotations: partial update preserves omitted fields, auto mode only applies to reviews written afterwards, AI-flagged reviews requiring a human are held rather than auto-answered, plus plan and write-scope prerequisites. This is exactly the extra context a mutation tool needs beyond readOnlyHint/destructiveHint.

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, front-loaded with 'WRITE tool —' so the operation class is immediately visible, and no filler. Every clause carries a distinct obligation or side effect.

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 covers mutation semantics, side effects, and prerequisites adequately for a 10-param config setter. It never mentions what the call returns or how to verify the new state, which is a minor residual gap rather than a blocker.

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 10 parameters (mode, ranges, caps, delays, localization) are already fully documented in the schema. The description adds mutation semantics but no per-parameter meaning beyond that, which is the correct baseline when 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 set (switch on/off, update) and the exact resource (the review responder for one of your own iOS apps), scoping it to 'own iOS app' so it is distinguishable from the config-reading sibling sonar_review_responder and from reply-level tools. An agent knows precisely what changes.

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: partial-update semantics ('omitted fields keep their value'), the Indie plan requirement and the auth/write-scope need. It does not explicitly name the sibling to read current settings (sonar_review_responder) or when to prefer it, so it stops short of full alternative 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 destructiveHint=true, idempotentHint=true and openWorldHint=true, so safety profile is covered. The description adds real context beyond them: the locale is auto-enabled on the set as a side effect, the fallback model, and plan/auth requirements. That is meaningful disclosure, though it doesn't spell out precisely what storing overrides destroys.

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; the core action and scope lead, then the fallback rule, then prerequisites. Every clause carries information and nothing is redundant.

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 purpose, fallback behavior, side effects (locale auto-enable) and access prerequisites, which is nearly everything an agent needs to invoke it correctly. Only a fuller account of what existing overrides are replaced would make it complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so locale, set_id and entries are already well documented in the schema, including the sparse-override keying and wholesale replacement semantics. The description only gestures at override types ('text copy, localized captures/images') without adding format or syntax detail, so it sits at the 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 (Write) and recognizable resource (a locale's translation overrides for screens in a screenshot set), and clarifies scope with examples '(text copy, localized captures/images)'. An agent can distinguish this from siblings like sonar_update_screenshot or sonar_update_screenshot_set without opening their 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 clear context for when to use it (writing per-locale overrides) and the governing rule 'geometry and styling always come from the source layout; anything not overridden falls back to it', plus prerequisites (Indie plan, authorized account or write-scope key). It does not name when-not to use it or point to an alternative sibling, so it stops short of a 5.

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

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

Goes well beyond the annotations: it explains that re-starring refreshes the timestamp and unstarring a non-starred keyword is a no-op (elaborating what idempotency means here), plus plan (Indie) and auth/write-scope prerequisites that no annotation conveys. This is exactly the extra behavioral context a write tool 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?

Four sentences, front-loaded with 'WRITE tool', each carrying distinct value (semantics, result effect, idempotency, requirements). 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 two-parameter write tool with no output schema, the description covers behavior, idempotency semantics, effect on downstream results, and auth/plan requirements. 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning to the `starred` flag by tying it to the starred_at timestamp surfaced in sonar_app_keywords results. It slightly exceeds the schema's own documentation.

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

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('stars or unstars') and resource ('tracked keyword') plus scope ('caller's Sonar workspace'), and defines what a star means. An agent can distinguish this from sonar_track_keywords/sonar_untrack_keywords without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'star = favorite/target' framing implies when to use it, but there is no explicit when-to-use/when-not statement or named alternative for the tracking operations. Usage is inferable but not 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?

Annotations only cover the safety profile (read-only, idempotent, open-world); the description adds genuinely new behavior: summary/movers/droppedApps always span the full top 200 while `limit` truncates entries only, movement is empty on the first request for a chart, responses arrive within ~30s with a `stale: true` + `measuredAt` fallback, and no API key is needed but free-tier daily use is IP-limited. These are exactly the operational facts 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?

The purpose and movement content are front-loaded, and each subsequent sentence carries a distinct operational fact (limit scope, first-day emptiness, 30s/stale behavior, auth tier). No sentence is filler or restates the name.

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

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

With no output schema, the description still characterizes the response shape (summary, movers, droppedApps, per-app rank delta, measuredAt) and covers the freshness/staleness contract. Combined with a fully documented 5-param schema and safety annotations, 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 the baseline is 3, but the description adds real semantics beyond the schema: `limit` truncates only the returned entries, not the summary/movers/droppedApps aggregates. It does not explain country/category key behavior 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?

The opening sentence gives a specific verb and resource with full scope: store-wide top charts (free/paid/grossing, overall or by category) plus day-over-day movement composition (rank delta, new entries, movers, drop-outs). That scope is unmistakably distinct from per-app siblings like sonar_app_rankings and sonar_keyword_rankings, so an agent can identify 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?

"Use to see what's rising in a market or category" gives a clear positive selection context. However, it names no alternative tool and states no when-not condition, so routing against near-neighbors (e.g. app-level rankings) is left 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 and openWorldHint=true, but the description adds genuinely new behavioral context: the WRITE nature, the 'at most one iOS + one Android app per product' constraint, the Indie plan requirement, and the auth/scope requirements. This is exactly the kind of value structured fields 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 tight sentences, front-loaded with the critical 'WRITE tool' classification, followed by the constraint, the alternative, and the prerequisites. No filler; every sentence earns its place.

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

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

For a write tool with 100% schema coverage, no output schema needed, and annotations covering safety, the description is complete: purpose, constraints, alternative, plan, and auth requirements are all present. 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 all four parameters (including the store_id formats and product UUID semantics) are already fully documented in the schema. The description adds no syntax or format detail beyond that, so the 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 (links) and resource (the second-store version of an existing Sonar product), and explicitly contrasts it with the sibling sonar_create_product used for brand-new apps. An agent can distinguish this from the other tracking tools 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?

Gives explicit when-to-use (adding the second store's version), when-not-to-use (brand-new app → sonar_create_product), and the preconditions (Indie plan, authorized account or write-scoped API key). Nothing is left 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, idempotentHint=false, destructiveHint=false, and openWorldHint=true, so the write/non-idempotent nature is covered structurally. The description adds real value beyond that: the 'WRITE tool' label, the plan tier requirement, and the auth model (authorized Sonar account or API key with write scope), 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?

Front-loads the 'WRITE tool' qualifier and then packs prerequisites and auth into two further sentences with little waste. Slightly dense, but every sentence carries actionable information (effect, precondition, 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?

With no output schema, the description still covers purpose, preconditions, plan gating, and auth, which is what an agent needs to invoke it correctly. It doesn't state what happens on a duplicate/pre-existing competitor (relevant given idempotentHint=false), a minor gap for a 4-param mutation.

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 parameters are fully documented at the schema level and the baseline applies. The description reinforces the store/product relationship ('same store as the competitor') but adds no syntax or format detail beyond what the schema already states for store, store_id, product_id, and country.

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 (adds/tracks) and resource (a competitor app under a Sonar product) with the downstream effect (keywords and rankings tracked alongside the product's own app). This cleanly distinguishes it from sibling sonar_track_app (own app) and sonar_remove_competitor (the inverse).

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: the product must already have its own app linked in the same store as the competitor, plus the Indie plan and authorized-account/write-scope requirements. It stops short of naming the relevant sibling alternatives (e.g., create the product first via sonar_create_product), so it's context-rich but not fully 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 asserts 'Idempotent: re-posting the same terms reports them as already_tracked instead of creating duplicates', but the annotations declare idempotentHint=false, which says repeated identical calls do have additional effects. This directly contradicts the structured hint. The remaining behavioral detail (plan caps, per-keyword outcomes, auth requirements) is genuinely useful, but the contradiction is the dominant signal here.

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 designation and the core action, then layers requirements and limits. Every sentence earns its place, though the single dense block of five ideas could be broken up slightly 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?

With no output schema, the description compensates by describing the return shape (per-keyword created / already_tracked / failed), the partial-success behavior at plan caps, and the required plan and auth scope. Nothing essential to invoking 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 the schema already documents app_id's origin, the country default, and the 1-200 keyword bounds. The description adds only that duplicates/already-tracked terms are reported rather than duplicated, which is behavior rather than parameter syntax, 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 ('starts daily rank tracking for one or more keywords on an app') plus the write nature, which cleanly separates it from read-side siblings like sonar_app_keywords and from sonar_untrack_keywords/sonar_star_keyword. An agent can identify the operation 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 preconditions for use: an Indie plan, an authorized Sonar account or API key with write scope, and the consequences of hitting the plan cap. It never names a sibling alternative (e.g., when to prefer star_keyword or app_keywords extraction over tracking), so it is strong context without explicit exclusions.

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, but the description goes well beyond them: it enumerates precisely what is destroyed (keywords with their notes and stars, discovered keywords, competitor links, and the product plus its screenshot sets if no other app remains) and what is preserved (shared store data — metadata, snapshots, rank history). This is exactly the kind of consequence detail annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with 'WRITE tool' and the core action, then ordered by consequence, alternative, and prerequisites. Dense but each sentence carries needed information for a destructive operation; minor length is justified 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?

For a destructive single-parameter tool with annotations covering the safety profile and no output schema, the description supplies everything an agent needs: the scope of deletion, what survives, plan/authorization requirements, and the correct sibling to use for a narrower task.

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 only one parameter, so the baseline is 3. The description adds no format or syntax detail about app_id beyond what the schema already states ('UUID ... NOT a store id').

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 ('untrack an app in the caller's Sonar workspace') and immediately enumerates the exact effects (tracked keywords, discovered keywords, competitor links, product detachment). This lets an agent distinguish it from sibling destructive tools like sonar_untrack_keywords or sonar_delete_product 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 an explicit alternative for a specific case ('To drop a competitor from one product use sonar_remove_competitor instead') and states prerequisites (Indie plan, authorized account or API key with write scope). Clear context is given, but there is no general when-not-to-use guidance covering the primary app-untracking operation.

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 description's 'WRITE tool' framing is corroborating rather than novel. It does add value beyond annotations by disclosing the plan requirement (Indie/trial counts) and the auth modes (account vs write-scoped API key), which annotations cannot convey. It does not describe the return payload or partial-failure behavior.

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, front-loaded with the WRITE classification and the mode-selection rule before the prerequisites. Every clause carries information, though the auth/plan sentence is somewhat packed.

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 destructive bulk mutation with no output schema, the definition covers the essentials: operation type, the two mutually exclusive modes, the alternative tool, and the plan/auth gates. Only the response shape and any partial-failure semantics are unaddressed, which is a minor 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%, so all three parameters are already documented, including the mutual-exclusivity rule the description repeats. The description adds the practical note that a single keyword should use the sibling tool instead, but no format or semantic detail beyond the schema.

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

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource+scope: 'bulk-untrack keywords for an app in the caller's Sonar workspace.' It explicitly distinguishes itself from the single-keyword sibling (sonar_delete_tracked_keyword), 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?

States the two mutually exclusive invocation modes (all:true vs ids:[...]), names the single-keyword alternative, and gives prerequisites (Indie plan, authorized account or write-scoped API key). This is explicit when-to-use guidance with an alternative named.

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

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

Goes well beyond annotations: specifies plan requirement (Indie), auth requirements (authorized account or API key with write scope), and idempotent semantics. The annotations declare idempotentHint=true, and the description reinforces it with the concrete 're-sending the same note is a no-op', adding operational detail the annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads 'WRITE tool' and the core action in the first sentence, then layers idempotency and auth compactly. Every clause earns its place, though the parentheses around examples could be trimmed.

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?

Covers the mutation semantics, idempotency, plan/auth prerequisites, and note-clearing use cases; with schema handling parameter detail and no output schema needed, an agent has everything required to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters are fully documented in the schema, including the null/empty-string clearing behavior and the ID disambiguation note. The description adds only a general phrase about notes; the baseline 3 applies when 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+resource ('sets or clears the note on a tracked keyword') with example use cases, and distinguishes scope ('caller's Sonar workspace'). An agent can tell it apart from sonar_star_keyword or sonar_track_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?

Implies usage via examples (why tracked, hypothesis, reminder) and produces a 'WRITE tool' label, but does not state when-not-to-use or name an alternative sibling for note clearing vs. other keyword mutations.

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