sonar

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. The description adds genuinely useful context beyond those: the append is positional (at the end), and it documents the auth requirement (authorized account or write-scope API key). It does not cover duplicate handling or any set-size limits.

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

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

Two tight sentences with the core action front-loaded, followed by the ordering caveat and the auth prerequisite. No filler and nothing 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 small two-parameter mutation with no output schema and annotations covering the safety profile, the description supplies the key missing pieces: positional behavior, sibling redirect, and auth requirements. The opaque nested 'layout' object is left to the schema and the sonar_screenshot_layout_guide sibling, which is acceptable.

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

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

Schema description coverage is 100%, so both set_id and layout are already documented in the schema, and the layout's 'omit for a blank screen' guidance lives there. The description adds no parameter-level detail beyond the positional 'at the end' note, so the baseline 3 for schema-carried semantics 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 and resource: 'Append a screen to a screenshot set,' which tells an agent exactly what mutation occurs. It partially differentiates from siblings by noting the append-at-end behavior and pointing to sonar_update_screenshot_set for reordering, though it does not draw a line against the other screenshot mutators (sonar_update_screenshot, sonar_create_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?

Gives a clear use context (appending at the end of an existing set) and an explicit redirect to sonar_update_screenshot_set when reordering is needed. It also names the prerequisite (authorized Sonar account or write-scope API key), but never contrasts this tool with sonar_update_screenshot or sonar_create_screenshot_set, so an agent must infer which sibling fits which case.

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 declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds real context beyond that: it works without an API key, is on a free tier, and is rate limited per IP per day — useful operational disclosure for a read-only tool.

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: purpose first, return shape second, operational constraint last. Front-loaded and free of 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 explains the return shape (overall score plus itemized checks), and annotations plus the rate-limit note round out the behavior. Only minor gaps remain, such as how scoring exceptions or missing data are surfaced.

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, and store_id are already fully documented in the schema (including the enum and defaults). The description adds no parameter-level detail, so the baseline of 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?

The description gives a specific verb ('Calculate') and resource ('ASO (App Store Optimization) audit score (0-100) for an app'), and enumerates the breakdown items (title length, keyword usage, screenshots, ratings). It is clear what the tool does, though it never explicitly distinguishes itself from related sibling tools like sonar_app_overview.

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 only implied via the benefit clause 'so you can identify what to improve.' There is no explicit when-to-use, when-not-to-use, or named alternative among the many sibling tools, leaving the agent to infer the right context.

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=false), so the description's burden is lower. It still adds useful behavioral context: results are ordered 'newest first' and gated behind an 'Indie plan (trial counts).' It does not describe pagination behavior or result cardinality beyond the schema's limit cap.

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, each earning its place: the first defines the returned data and ordering, the second gives the use case. Information is front-loaded with no filler or 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?

Covers purpose, change types, ordering, use case, and a plan-gating requirement for a read-only, 3-parameter tool with full schema coverage. The absence of an output schema means the description could have described the return shape, but for a simple list tool the current coverage is close to sufficient.

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 app_id, type, and limit with clear descriptions. The description adds no field-level syntax or format details beyond what the schema provides. Baseline 3 applies 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+resource (change history) and enumerates the exact change types returned (releases, metadata edits, screenshot swaps, price changes, category moves). This clearly distinguishes it from siblings like sonar_app_rankings or sonar_app_overview, which do not track change events.

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 a concrete use case: 'correlating rank movements with what the app (or a competitor) changed.' This implies when to reach for this tool, but does not explicitly name a sibling alternative or state when NOT to use it, so it falls short of the 5-level bar.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: it works without an API key and is subject to a free tier with limited daily use per IP, a rate-limit/auth trait not present in the annotations.

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

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

Three sentences that are front-loaded with the core action and free of filler; each sentence (purpose, use case, constraint) carries distinct information. Minor slack in the second sentence's parenthetical, but overall tight.

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 adequately conveys what the tool produces (relevance-ranked keywords) and the cost/auth constraint. It is complete enough for a simple read-only extraction tool, though it omits return-format or count details that a reader might expect.

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

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

Schema description coverage is 100%, so every parameter (max, store, country, store_id) is already documented in the schema with enums, defaults, and format notes. The description adds no parameter-level detail beyond the schema, which is the expected baseline 3 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 and resource (extract target keywords from an app's title and description, ranked by relevance), which is more precise than the tautological title. It implicitly distinguishes itself from sibling keyword tools by describing the extraction-from-text method, but never names an alternative like sonar_app_keywords or sonar_discovered_keywords to make the boundary explicit.

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" gives a concrete use case, implying when the tool fits. However, it offers no exclusions and does not compare against the many sibling keyword tools (sonar_app_keywords, sonar_competitor_keywords, sonar_keyword_suggestions), so the agent must infer which keyword tool to 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, 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 non-destructive, so safety is covered. The description adds genuinely new behavior: it discloses the authentication model (no API key needed) and a rate limit ('limited daily use per IP'), which the agent cannot learn from the schema or annotations.

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

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

Three sentences, each load-bearing: what it does, what it returns, and the auth/rate-limit constraint. The core purpose is front-loaded with zero 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, so naming the returned fields (name, developer, category, rating, reviews, installs, price) usefully compensates, and auth plus rate limits are covered. The remaining gap is routing among near-identical siblings, which is unaddressed.

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, country, and store_id each carry their own format documentation, including iOS numeric track ID vs Android package name. 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?

States a specific verb and resource ('look up a single app by its store ID') and enumerates the returned metadata, so the agent knows exactly what it gets. However, it never distinguishes itself from close siblings like sonar_get_app or sonar_app_overview, leaving the agent to guess which lookup tool to pick.

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 notes it works without an API key on a free tier with limited daily use per IP, which is useful operational context. But it gives no guidance on when to use this versus sonar_get_app, sonar_app_overview, or sonar_app_search, and no prerequisite or exclusion conditions.

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

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

Annotations already cover readOnly, idempotent, and non-destructive status, so the bar is lower. The description adds a real behavioral detail beyond structured data: the tool requires an Indie plan (trial counts), which an agent needs to know before calling. It does not mention pagination or response limits, but the plan gating is valuable added context.

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 'read this FIRST' instruction are front-loaded, and every listed item corresponds to returned data, so the length is largely earned. The opening sentence is a dense enumeration that could be trimmed, but there is 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?

With no output schema, the description carries the full burden of describing return values and does so thoroughly, covering every section the dashboard renders. The plan requirement and the single-call framing complete what an agent needs to invoke and interpret 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 (days, app_id) are already fully documented in the schema, establishing the baseline of 3. The description adds no meaning about the days window or app_id format beyond what the schema provides, and even the 7-day deltas it mentions are output, not input semantics.

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

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

States a specific resource and scope: the computed dashboard scoreboard for one app in a single call, then enumerates its contents (visibility index, share of voice, keyword counts, movement, opportunities). It clearly positions itself as the aggregated answer versus raw rank history. It does not name which specific sibling (e.g., sonar_app_aso_score or sonar_app_rankings) it supersedes, so sibling differentiation is implied rather than explicit.

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?

'Read this FIRST when asked how an app is doing' gives explicit triggering context, and 'you don't need to recompute anything from raw rank history' implies the alternative (rank history) to avoid. No hard exclusions or explicit named alternatives are given, but the usage context is clear.

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 already declare readOnly, idempotent, non-destructive, open-world behavior, lowering the bar. The description adds valuable context about return content (dollar estimate, confidence grade, factors, methodology) and an operational rule to always report confidence, going 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?

Two tightly constructed sentences, front-loaded with the core purpose and immediately followed by return value details and an important operational instruction, with no wasted words.

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?

The description covers what the tool does, its inputs, return values, and a usage caveat. Since annotations cover safety and there is no output schema, only a bit more detail on when to prefer this over alternatives would make it fully complete.

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

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

Schema description coverage is 100%, so the schema fully documents parameters; the description adds no parameter-specific details. Baseline 3 is appropriate when the schema already covers parameter semantics.

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

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

The description clearly states a specific verb (estimate) and resource (monthly app revenue) and the inputs it uses (installs, ratings, category benchmarks). It doesn't explicitly contrast with siblings like sonar_app_aso_score or sonar_portfolio, but its unique estimation purpose is evident.

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?

No guidance on when to use this tool versus similar siblings (e.g., sonar_app_aso_score, sonar_portfolio) or prerequisites is provided; the only implied usage is about communicating confidence, not about selecting the tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds filtering and sorting capabilities and use-case context, but does not disclose behavioral traits like pagination, rate limits, auth requirements, or return format.

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 tightly written sentences with the primary action front-loaded; no filler or redundancy. The second sentence efficiently summarizes supported filters and intended uses.

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 an eight-parameter fetch tool with full schema coverage and safety annotations, the description is largely complete. It covers what the tool does and its filtering options, though it does not describe the shape of returned review data (e.g., fields, pagination) despite having no output schema.

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

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

Schema description coverage is 100%, so the schema fully documents all eight parameters including the rating-range filters and sort options. The description merely restates the filtering and sorting features without adding syntax, format, or edge-case meaning beyond the schema.

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

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

States a specific verb ('Fetch') and resource ('user reviews for an app'), making the basic purpose clear. However, it does not distinguish this raw-fetch tool from sibling tools like sonar_review_insights or sonar_generate_review_insights, which likely provide derived analysis rather than raw reviews.

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 lists use cases (sentiment analysis, feature-request mining, competitive research) but gives no explicit when-to-use guidance, prerequisites, or alternatives to this tool. Usage is implied rather than directed.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond annotations: results come back in store ranking order, and the tool works without an API key under a free tier with per-IP daily limits. It does not mention pagination or rate-limit response behavior, keeping it out of 5 territory.

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 store scope, then ordering behavior, then auth/quota caveat. 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?

Complete enough for a read-only search tool: the purpose, result ordering, and auth/quota constraints are covered, and the schema fully documents parameters. The absence of any mention of result limits relative to `num` or rate-limit error behavior is a minor gap, but no output schema exists that would otherwise cover 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%, so all four parameters (num, query, store, country) are already documented with defaults, ranges, and enum meaning. The description adds no parameter-level syntax or format detail, 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 (search) and resource (apps) with the scoping detail that it queries the App Store or Google Play by keyword. This distinguishes it clearly from siblings like sonar_app_lookup (fetch by id) and sonar_list_apps (list tracked apps).

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

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

The description implies usage (keyword search across two stores) but never names alternatives or says when to prefer this over sonar_app_lookup or sonar_list_apps. An agent must infer the routing from names alone.

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 declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds valuable context beyond that: the Indie-plan prerequisite and trial-count consumption, plus a detailed inventory of what is returned (live stats, top rows, AI insight), which helps the agent anticipate cost 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 purpose and scope, followed by a dense but useful enumeration of return contents. It is a single long sentence, but each clause (stats categories, top rows, AI insight, plan requirement) carries distinct information, with little true 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, so the description must carry return-value burden, and it does so thoroughly: it lists the stat categories, the top gap/threat/lead rows with metrics, and the optional AI insight contents. Combined with the plan prerequisite and the single fully-documented parameter, 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%, and the schema already documents app_id richly (own app UUID, not a store id, not a competitor id). The description's 'one of your own apps' is consistent but adds no syntax or format detail beyond the schema, so 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?

The description states a specific resource and scope: 'The full competitive keyword picture for one of your own apps vs every tracked competitor, in one call,' then enumerates the concrete contents (gaps, winnable gaps, climbers, leads, top rows, AI insight). It distinguishes itself from narrower siblings like sonar_competitor_keywords/sonar_analyze_competitors by framing itself as the aggregate 'full picture' delivered in a single call.

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?

'Read this before deciding which keywords to target next' gives a clear usage context, and the plan gating ('Requires an Indie plan') sets a precondition. However, it never explicitly names the alternatives (e.g. sonar_competitor_keywords for a narrower slice) or states when NOT to use it, so it stops short of explicit 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?

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds valuable context beyond annotations: it states the required plan (Indie), authorization needs (authorized account or API key with write scope), and the fact that it starts tracking the given apps. It also discloses returned ids, which is useful for workflow planning. Missing rate limits or error behaviors, but for a creation tool this is strong.

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 operation type and scope, then workflow dependencies, then prerequisites. Every sentence adds distinct value; 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 write tool with a clear schema and annotations, the description covers the essential: what it does, what it returns, dependencies, and authorization/plan requirements. It lacks details on error conditions or rate limits, but these are not critical for correct invocation. The absence of an output schema means the description appropriately compensates by stating the returned values.

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

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

Schema description coverage is 100%, so the schema fully documents the 'apps' and 'name' parameters. The description adds no additional syntax or format details beyond what the schema provides (e.g., doesn't explain the 'country' default or 'store_id' format nuances). Baseline 3 is appropriate 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 ('creates') and resource ('a product in the caller's Sonar workspace'), and clarifies the domain concept ('cross-store unit: one iOS + one Android app'). It distinguishes itself from siblings by referencing the downstream tools (sonar_track_keywords, sonar_track_competitor) and the returned ids, which helps an agent understand its role in the workflow.

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

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

Clearly signals it's a prerequisite for sonar_track_keywords and sonar_track_competitor by returning the necessary ids, effectively telling the agent when this tool is needed. However, it doesn't explicitly state when *not* to use it or contrast with alternatives like sonar_list_products or sonar_delete_product beyond the sibling reference.

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 (write, non-idempotent, open-world, non-destructive), and the description adds real value beyond them: the set becomes immediately visible/editable for humans in the Screenshot Studio, and it requires an authorized Sonar account or write-scope API key. Auth and side-effect context are disclosed; rate limits or failure behavior are not.

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 with zero waste, front-loaded with the action and then the prerequisite and constraint. Every sentence carries information an agent needs.

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

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

For a non-idempotent write tool with annotations but no output schema, it covers auth requirements, the prerequisite guide, and the human-visible side effect including where studio_url appears. Nothing critical is missing, though return-value detail remains thin.

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

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

Schema description coverage is 100%, so all six parameters (including the screens/template_id exclusivity and the device_size example) are already documented in structured form. The description reinforces authoring the screens array but adds no syntax or format 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?

Specific verb + resource ("Create an app-store screenshot set for a product") with clear scope. It is readily distinguishable from sibling read/update/delete screenshot 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?

States a prerequisite ("Read sonar_screenshot_layout_guide first, then author the screens array") and the schema documents the screens-vs-template_id choice. It doesn't explicitly say when to prefer sonar_add_screenshot or the update tool instead, 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 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; the description goes beyond them by disclosing the cascade ('untrack its apps'), the required plan tier, and the auth/scope requirement. That is exactly the extra context an agent needs before invoking a destructive write.

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 short sentences, front-loaded with the 'WRITE tool' signal so the agent sees the mutation nature immediately. 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?

One required parameter fully described, annotations covering safety/idempotency, and the description supplying cascade behavior, plan, and auth requirements. No output schema exists, so return-format documentation is not needed.

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 product_id parameter is fully documented, including that it is the UUID returned by sonar_list_products/sonar_create_product. The description adds no further parameter detail, 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 ('delete a product') plus the scope ('in the caller's Sonar workspace') and an important secondary effect ('untrack its apps'). Unambiguous against siblings like sonar_delete_alert or sonar_delete_screenshot because the resource is named.

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: an Indie plan and either an authorized Sonar account or an API key with write scope. It does not name alternatives or state when-not to use it (e.g. use sonar_untrack_app to remove only apps), 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 cover destructive/idempotent hints, but the description adds genuine context beyond them: the invariant that a set must retain one screen, and the auth requirement (authorized Sonar account or write-scope API key). It doesn't disclose the rejection response shape, but with annotations carrying the safety profile this is solid.

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

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

Three tight sentences, each earning its place: purpose, the constraint, and the auth requirement. Front-loaded with the core action.

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 annotations covering safety, this covers purpose, a key invariant, and auth. The one missing piece is what happens on the last-screen rejection (error vs. no-op), but otherwise complete.

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

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

Schema coverage is 100% with the lone parameter (screenshot_id) already documented as 'Screen id to delete.' The description adds no format, syntax, or sourcing detail beyond what the schema provides, so the baseline 3 applies.

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

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

Specific verb (delete) plus precise resource (one screen from a screenshot set). Distinguishes itself from siblings like sonar_delete_screenshot_set and sonar_update_screenshot by explicitly narrowing scope to a single screen.

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 a concrete precondition — a set must keep at least one screen, so deleting the last is rejected — which steers the agent away from invalid calls. Does not, however, point to alternatives (e.g. sonar_delete_screenshot_set) for removing everything.

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 readOnlyHint=false, so the bar is lower. The description still adds real value by spelling out the cascade (screens and translations are deleted) and the auth requirement (authorized account or write-scope API key), which annotations do not cover.

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 action, followed by the irreversibility warning and auth prerequisite. No filler; each 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 single-parameter, no-output-schema tool whose annotations cover the safety profile, the description supplies the cascade scope, irreversibility, confirmation prompt, and auth requirement. 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?

Only one parameter (set_id) and schema description coverage is 100%, so the schema fully documents it. The description adds no syntax or format detail beyond the schema, 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) plus the cascade scope ('everything in it (screens, translations)'). This clearly differentiates it from siblings like sonar_delete_screenshot (singular) and sonar_delete_product.

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 caution guidance ('confirm with the user before deleting work they may want'), but names no alternative tool for callers who should modify rather than remove a set (e.g., sonar_update_screenshot_set). Usage is implied rather than explicitly routed.

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 destructiveHint=true and idempotency; the description adds plan requirements (Indie) and auth/scope prerequisites not present in annotations. It does not state the reversibility or response behavior, but the auth/plan context is genuinely additive.

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 write classification and identity source are front-loaded, and every clause carries operational value.

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-param destructive tool with full annotation coverage, this covers scope, identity source, plan, and auth. It stops short of stating irreversibility or confirming whether re-deleting is a no-op, which would complete the picture.

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

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

Schema coverage is 100% and the schema itself already warns the id is the UUID, not the keyword_id. The description references that source but adds no syntax or format detail 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+resource ('stop tracking one keyword/app pair') and names the exact identifier source (tracked-keyword id from sonar_app_keywords). Distinguishes itself from bulk siblings like sonar_untrack_keywords and sonar_untrack_app by scoping to a single pair.

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?

Clear context is given — single-pair untracking, plan and auth prerequisites. However, it does not explicitly contrast with sonar_untrack_keywords or sonar_untrack_app, which an agent choosing between them would need.

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

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

Annotations already cover read-only/idempotent/non-destructive safety, so the description correctly focuses on added context: the Indie plan requirement, the three classification buckets, returned fields, and best-first opportunity ordering. It does not cover pagination or rate limits, but the added behavioral context is substantial.

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 scope, then adds classification detail and next steps. It is dense but every clause carries useful information; em-dash-heavy phrasing makes it slightly less scannable than ideal.

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 no output schema, the description usefully explains what is returned (popularity, difficulty, AI relevance, opportunity score) and the plan requirement. With annotations and schema covering safety and filtering, the remaining gap is minor, such as default status/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 coverage is 100%, so the schema already documents all eight parameters, including the bucket enum and opportunity score range. The description restates bucket meanings and the opportunity score scale, adding clarity but little beyond the structured 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 resource (untracked keywords from Sonar's discovery engine) and clearly differentiates it from tracked-keyword tools by emphasizing 'that aren't tracked yet.' It also names the follow-up sibling sonar_track_keywords, so an agent can distinguish it 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 explicit context: read to find 'what should I track next,' pick winners, then use sonar_track_keywords. This is a clear when-to-use and next-action path, though it stops short of naming when-not-to-use or direct alternatives like sonar_keyword_suggestions.

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 cover the safety profile (readOnly, idempotent, non-destructive). The description adds behavioral context beyond annotations: the default placeholder substitution for image data and the note that placeholders are rejected on update — operationally relevant for a read tool feeding a later write.

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

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

Two tight sentences, front-loaded with what is returned, then the default behavior caveat. 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?

Covers return contents and the default image-data behavior, which is the main gotcha for this read tool. No output schema exists, so the description carries the return-shape burden — it does this adequately but does not describe structure of the layout JSON or locale keying beyond the one phrase.

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 (set_id, include_image_data) are already fully documented in the schema, including the default and the placeholder rationale. The description mirrors the same fact rather than adding new syntax or format details. 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 (fetch) and resource (screenshot set) with scope detail: 'in full: every screen's layout JSON plus per-screen translation overrides keyed by locale.' This distinguishes it from sonar_list_screenshot_sets (which lists) and sonar_get_screenshot_set-style siblings, though it doesn't explicitly name those 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?

Implies usage via 'Fetch a screenshot set in full' but does not state when to use this vs sonar_list_screenshot_sets or when you need full data vs a summary. No explicit alternatives 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: discloses the 1-credit-per-keyword cost model, free-tier cap of 5 keywords/day per IP, API-key removal of the cap, and the `pending` state (queued, not charged) with retry_after_seconds re-check advice. Annotations only cover readOnly/idempotent safety; this adds the operational behavior that actually matters for invocation.

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 primary purpose, then cost, then limits, then sibling alternative, then edge-case handling. Every sentence earns its place; 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?

Complete for a read-only metric tool with no output schema: covers purpose, cost, auth/free-tier, sibling routing, and the async pending/retry edge case. 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 baseline is 3, but the description adds value beyond it: it clarifies the bulk-vs-single distinction ('or up to 25 in bulk') and that they are mutually exclusive, and that the pending/retry behavior is a return-value trait tied to keyword computation. Slightly above baseline for reinforcing the key constraint.

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 ('Difficulty + popularity for a specific keyword') and explicitly contrasts with the sibling sonar_keyword_search ('use sonar_keyword_search instead when you want related keyword ideas'). An agent can distinguish it from siblings immediately.

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 a named alternative with its selection condition ('sonar_keyword_search ... when you want related keyword ideas alongside metrics'). Credit-cost and free-tier limits add actionable routing context.

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 already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered; the description adds value by disclosing the return payload (difficulty scale, popularity, results count, autocomplete suggestions) in the absence of an output schema. If a schema existed, this disclosure would be redundant, but here it is genuinely useful.

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, zero filler, outputs front-loaded before the usage hint. 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 read-only research tool with full schema coverage and complete annotation coverage, the description supplies what structured fields don't: the shape of the return value. The only shortfall is the unaddressed overlap with sibling keyword tools, which an agent must disambiguate on its own.

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% – query, store, and country each carry their own documentation including the ISO code format and defaults – so the schema does the work. The description adds no parameter-level detail beyond what the schema already states, 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+resource (research a keyword and related terms) and enumerates the outputs (difficulty 0-100, popularity score, results count, autocomplete suggestions). Clear on its own, but it never distinguishes itself from close siblings like sonar_keyword_metrics or sonar_keyword_suggestions, several of which also return keyword metrics.

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

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

"Use this to find keywords worth targeting" implies intent but names no alternative and gives no when-not condition, which is a real gap given the dense cluster of keyword tools (keyword_metrics, keyword_suggestions, keyword_rankings, app_keywords). Usage is only vaguely implied rather than routed.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the description correctly spends its words on things annotations cannot express: no API key needed, free tier, and per-IP daily usage limits. It omits result-count limits or pagination behavior, 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 tight sentences with zero filler: purpose, output shape, sibling differentiation, and the free-tier caveat. The differentiating constraint (lighter/faster) is front-loaded rather than 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?

With no output schema, the description does describe the return shape (terms with a priority score, higher = more searched) and the access/rate-limit context. It doesn't state how many suggestions come back or whether country materially changes results, a minor residual gap.

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

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

Schema description coverage is 100%, so seed, store, and country are all already documented with format details (ISO code, default 'us', enum values). 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 names a specific verb (get autocomplete suggestions) and resource (for a seed keyword from the App Store or Google Play), and explicitly contrasts itself with the close sibling sonar_keyword_search. An agent can distinguish it from other keyword 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 gives an explicit when-to-use condition ('use when you only need term ideas without difficulty/popularity scoring') and names the alternative tool by name. The routing decision between the lightweight suggestions tool and the heavier search tool 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 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 establish readOnly, idempotent and non-destructive behavior, so the bar is lower. The description adds a genuinely useful constraint not present in structured data: it requires an Indie plan (trial counts), which is real auth/entitlement context an agent needs before calling.

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

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

Three short sentences, front-loaded with what is returned, then the use case, then the plan requirement. No filler and every sentence carries 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 parameterless list tool with no output schema, the description covers what comes back, what it is good for, and the plan gate. The only minor gap is the absence of guidance relative to the sibling list_apps/portfolio tools.

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 schema is an empty object, so there is nothing for the description to clarify. Baseline for a 0-param 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 and resource (list products) and adds the return contents (linked store versions and competitor counts), plus a secondary purpose (discover product/app UUIDs). It does not explicitly differentiate itself from the similar sibling sonar_list_apps or sonar_portfolio, so it stops short of a 5.

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

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

Provides one concrete usage context ('Use it to discover product/app UUIDs'), which is more than a bare listing tool usually offers. However, it gives no when-not guidance and never names an alternative among the many list_* siblings, so usage 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds useful context beyond annotations by defining the shape of the return (metadata fields only, not full layouts), which steers the agent away from expecting layout data. It doesn't mention pagination or rate limits, hence not 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?

One sentence for what it returns, one sentence for the alternative. Zero waste, front-loaded with the resource and the metadata-only scope.

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, read-only list tool with no output schema, the description covers purpose, scope, and the alternative lookup tool. Missing only minor operational details like pagination or result ordering, which are not critical here.

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

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

Schema coverage is 100% and the schema itself documents product_id, including a pointer to sonar_list_products. With only one parameter fully documented in the schema, the baseline is 3; the description adds no new parameter detail, but the single-param and fully documented nature keeps it above baseline. Slight lift because it clarifies product scoping in prose.

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 (List) and resource (app-store screenshot sets), and explicitly scopes the output to metadata only, enumerating the fields. It names the sibling sonar_get_screenshot_set for full layouts, so the agent can distinguish it from get_screenshot_set and create/update_screenshot_set 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?

Explicitly names the alternative (sonar_get_screenshot_set) and the condition that selects it (when full layouts are needed). The verb 'list' plus the 'metadata only' qualifier makes the when-to-use boundary clear.

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?

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds material context beyond them: it is a WRITE operation requiring an Indie plan (trial counts) and an authorized account or write-scoped API key, which is useful permission/auth information an agent cannot derive from annotations alone.

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

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

Two compact sentences with the mutation flag and the action front-loaded, followed by requirements. No filler, no repetition of schema 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?

For a two-parameter destructive mutation with full schema coverage and annotations covering the safety profile, the description supplies the missing pieces (auth, plan tier, write scope). With no output schema required and IDs documented in the schema, nothing an agent needs to invoke this correctly is 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 description coverage is 100% and both parameters are documented with UUID guidance and pointers to sonar_list_products/sonar_create_product, including the explicit warning that competitor_app_id is the app UUID and not a store id. The description adds nothing further about the parameters, so the baseline 3 applies.

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

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

The description names a specific verb and resource: 'remove a competitor from a product in the caller's Sonar workspace', and the 'WRITE tool' prefix immediately flags it as a mutation. It is clear what the tool does, but it never contrasts itself with the adjacent competitor tools (sonar_track_competitor, sonar_scan_competitor, sonar_analyze_competitors), so the removal-vs-tracking boundary is left to inference.

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

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

It supplies prerequisites (Indie plan, authorized account or API key with write scope) rather than when-to-use guidance. There is no statement of when to pick this over tracking/untracking a competitor or scanning it, so usage is only implied by the verb.

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?

Goes well beyond annotations: discloses that it's a write/mutation that generates and queues keywords, verifies only the first batch inline (~30s), leaves the rest to background verification over hours, and records both apps' ranks. It also states plan and auth requirements, which annotations do not cover and which materially affect whether the call will succeed. Consistent with readOnlyHint=false.

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

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

Front-loaded with 'WRITE tool' and then sequenced through generate/queue/verify plus the read pointer. It is dense—several clauses packed into one long sentence—but essentially every clause carries decision-relevant information, so little 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?

Despite no output schema, the description explains the return payload (generated/queued/verified_now counts), the asynchronous completion window, and where to read the finished results. For a 2-param async write tool this covers everything an agent needs to invoke and follow up 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 UUID params are already documented with meaning (own app vs competitor, with the note that competitor_app_id is a Sonar UUID, not a store id). The description adds only indirect hints ('competitor's listing', 'both apps' ranks') and no syntax 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?

Specific verb+resource: 'runs an AI keyword discovery scan on a tracked competitor' with the concrete sub-effects spelled out (generates terms, queues for SERP verification, verifies first batch inline). It also names the read sibling sonar_competitor_keywords so the agent can distinguish this write from the read path immediately.

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 precondition (competitor must be tracked; own and competitor apps required), the alternative for reading results ('read results with sonar_competitor_keywords'), and access prerequisites (Indie plan, authorized Sonar account or write-scoped API key). Explicit routing and prerequisites leave 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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description still adds genuinely useful context that annotations cannot: the meaning of 'canvas dimensions' as the pixel coordinate space all layouts use, and that devices are grouped by store. It does not mention whether the list is static or paginated, which keeps it below a 5.

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

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

Two sentences, zero filler. The primary content (what is listed and what each entry contains) is front-loaded, and the call-to-action comes last.

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 reasonably: device sizes, canvas dimensions with their coordinate meaning, and store membership. The only gap is not stating how devices are identified/named for use in sonar_create_screenshot_set.

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 there are no argument semantics to clarify; the baseline for a parameterless tool is 4. The description correctly implies a no-argument enumeration by framing this as a catalog lookup.

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 screenshot devices) plus scope: device sizes supported for app-store screenshot sets, with canvas dimensions and store membership. An agent can immediately distinguish this from siblings like sonar_list_screenshot_sets or sonar_create_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?

Explicitly routes the agent into the workflow: 'Pick a device here before sonar_create_screenshot_set,' naming the downstream tool and the ordering constraint. No when-not guidance or mention of the layout guide alternative (sonar_screenshot_layout_guide), 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, destructiveHint=false, so safety is covered. The description adds the useful behavioral constraint that it should be called ONCE (idempotency reinforcement) and lists the content domains. It doesn't describe return size or format, but with readOnly+idempotent annotations the description meets the lower bar without exceeding it.

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

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

Two sentences, front-loaded with the core purpose then the timing rule. The enumerated topic list is dense but earns its place as a preview of contents. Minor verbosity in the middle of the list, but 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?

For a zero-parameter read-only reference doc with no output schema, the description tells the agent what the doc contains and when to consult it. The absence of an output schema means it could hint at whether the return is markdown/JSON, but that's a minor gap given the documented content 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?

Zero parameters, so per rubric the baseline is 4. No schema to compensate for and no wasted parameter discussion. Nothing here needs additional explanation.

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

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

States a specific resource ('layout-format reference for Sonar screenshot sets') and enumerates the exact topics it covers (JSON schema, coordinate system, image handling, fonts, translation overrides). An agent can tell it's a reference doc, not an action tool. Loses a point because it doesn't name a sibling alternative (e.g., sonar_create_screenshot_set, sonar_update_screenshot_set) that an agent might confuse it with.

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

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

Explicitly says when to use: 'Call this ONCE before creating or editing screenshot layouts.' The 'ONCE' qualifier is valuable timing guidance. Missing an explicit statement of when NOT to call it (e.g., after you already know the schema) or which siblings pair with 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 indicate readOnlyHint=false, which aligns with the description's 'WRITE tool' and 'create or update' wording, so there is no contradiction. The description adds valuable behavioral context beyond annotations: it discloses the upsert semantics, the dependency on an Indie plan, and the need for authorization/API key write scope. This goes beyond what annotations provide.

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

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

The description is three sentences with no fluff. It front-loads the core purpose, then the upsert behavior, then the key usage notes. Every sentence adds information an agent needs to call the tool correctly.

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?

The description covers the tool's purpose, write behavior, upsert semantics, parameter defaults, and authorization requirements. There is no output schema, but the description does not describe the response format or error behavior. For a write tool this is a minor gap; an agent knows it will return a confirmation or the created/updated alert, but explicit guidance would be slightly better.

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 each parameter is documented in the schema. The description adds extra usage semantics: for `threshold` it clarifies omitting uses per-type default; for `scope_app_id` it clarifies omitting makes an org-wide rule. It also expands on the `top_chart` type in the enum description. This adds meaning beyond the schema's basic descriptions.

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

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

The description clearly states the tool is a write tool that creates or updates alert subscriptions, with explicit reference to the resource (alert subscription) and scope (caller's Sonar workspace). It also distinguishes itself from siblings like sonar_list_alerts and sonar_delete_alert by focusing on create/update.

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 explains when to use the tool (to create/update alerts) and provides concrete usage guidance: how to trigger an update (re-submitting same type/scope), how to use defaults (omit threshold, omit scope_app_id), and what conditions apply (Indie plan, authorized account). It implicitly routes to alternatives like listing or deleting alerts, which are clearly distinct 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 declare destructiveHint=true and idempotentHint=true, but the description adds crucial context beyond them: that overrides replace stored values wholesale, that geometry/styling always come from the source layout, that the locale is auto-enabled on the set, and that authorization is required. These are meaningful behavioral facts 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?

Three dense sentences, front-loaded with the core action and scope. No wasted words. Slightly dense on the fallback constraint before the auth note, but structure is sound.

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-param, 100%-coverage mutation tool with no output schema, the description covers scope, fallback behavior, side effect (locale auto-enable), and auth. Missing only a destructive-fallout note (whether prior overrides are lost — actually implied by schema 'replaces wholesale') and return-value expectations, which is acceptable given no output schema.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds the semantic that overrides are keyed by layer id and fall back per-field, but the schema already covers locale format, screenshot_id, and the sparse override shape in 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 (write/override) + resource (locale translations for screens in a screenshot set) with clear scope. Distinguishes from sibling sonar_update_screenshot and sonar_get_screenshot_set by naming the translation-override behavior 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?

Explains the fallback semantics ('anything not overridden falls back to source') which implies context of use, and mentions auth requirements. But it never names a sibling alternative or states when NOT to use it (e.g., vs. sonar_update_screenshot for base copy). Usage is implied rather than routed.

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?

Goes well beyond the readOnly/idempotent annotations by disclosing that summary, movers and droppedApps always describe the full top 200 regardless of `limit`, that movement is empty on the first day a chart is requested, and that no API key is needed but free-tier daily use per IP is rate-limited.

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 returns, then usage, then the two caveats an agent could get wrong. Every sentence carries distinct information with no filler.

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

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

With no output schema, the description compensates by enumerating the return shape (per-app rank delta, new apps, biggest movers, dropped apps) plus the limit/aggregate caveat, making it complete enough to call correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics the schema lacks: the exact truncation behavior of `limit` versus the full-200 aggregates, and the day-over-day delta semantics tied to chart requests.

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 with scope modifiers ('store top chart (free / paid / grossing, overall or by category) with day-over-day movement'), which cleanly separates it from siblings like sonar_app_rankings and sonar_app_overview.

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

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

Gives an explicit use case ('Use to see what's rising in a market or category'), which tells the agent the right context. It does not, however, name or exclude a sibling alternative for chart-adjacent queries.

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 (write, non-idempotent, non-destructive, open-world), so the description's job is to add beyond that. It does: plan gating, auth/scope requirements, and the cardinality rule that a product holds at most one iOS + one Android app. It stops short of saying what happens if the slot is already occupied or if the store_id doesn't resolve.

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 dense sentences, front-loaded with the 'WRITE tool' signal and the core action before the example, alternative, and prerequisites. Every clause carries information; none is redundant with the 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 four-parameter write tool with no output schema, the description covers action, alternative, prerequisites, and the cardinality constraint. Only the failure/edge-case behavior (slot already filled, unresolvable store_id) is absent, which is a minor 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%, including the enum values, country code format, and the iOS-track-ID vs Android-package-name distinction for store_id, so the schema does the heavy lifting. The description adds no parameter syntax or format detail beyond that, making the baseline 3 correct.

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

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

States a specific verb and resource ('links the second-store version of an existing Sonar product') and immediately illustrates it with a concrete iOS/Android example. It also distinguishes itself from sonar_create_product by scope, 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 ('the product already tracks the iOS app and you want to add the Android version'), explicit when-not ('to start tracking a brand-new app, use sonar_create_product instead'), and names prerequisites (Indie plan, authorized account or write-scope 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 write (readOnlyHint=false), non-idempotent, non-destructive, open-world. The description adds valuable context beyond annotations: plan requirements (Indie, trial counts), authorization needs (account or API key with write scope), and the prerequisite that the product must have its own app in the same store. It doesn't detail error behavior or rate limits.

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

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

Two well-structured sentences that front-load the write nature and core behavior, then layer prerequisites and requirements. Minimal waste; slightly dense but appropriate for the tool's constraint set.

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 the critical preconditions (linked product app, plan level, authorization scope) and the core effect (tracking competitor keywords/rankings). It could mention whether tracking is immediate or async, but the essential context for correct invocation 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 description coverage is 100%, so the schema already documents store, country, store_id, and product_id thoroughly, including the key distinction that product_id is a Sonar UUID (not a store id) and store_id is the competitor's store-specific identifier. The description adds no parameter-level detail beyond what the schema provides, 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 (adds/tracks) and resource (competitor app under a Sonar product) with clear scope: keywords and rankings get tracked alongside the product's own app. It is clearly distinguishable from siblings like sonar_remove_competitor, sonar_scan_competitor, and sonar_analyze_competitors.

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

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

Gives clear preconditions for using this tool — the product must already have its own app linked in the same store, and an Indie plan plus authorized account/API key with write scope are required. It does not explicitly name alternative tools (e.g., scan vs analyze vs track), but the when-to-use 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?

The description explicitly claims 'Idempotent: re-posting the same terms reports them as already_tracked instead of creating duplicates', which directly contradicts the annotation idempotentHint=false. Otherwise it does add valuable behavior detail (per-keyword created/already_tracked/failed outcomes, plan and auth prerequisites), but the contradiction with the structured hint is a serious inconsistency that can lead an agent to wrong retry logic.

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 with the WRITE marker and purpose front-loaded, then dedup behavior, then return shape and prerequisites. No filler and nothing repeated from the schema.

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

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

With no output schema, the description compensates by naming the return shape (per-keyword created/already_tracked/failed) and by covering the non-obvious gating conditions (Indie plan, write scope). Everything needed to invoke it 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 description coverage is 100%, so app_id (UUID, not a store id), country (defaults to product country) and keywords (1-200, max 120 chars) are already fully documented in the schema. The description adds no parameter-level 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+scope: 'starts daily rank tracking for one or more keywords on an app'. It is clearly distinguishable from siblings like sonar_star_keyword, sonar_delete_tracked_keyword and sonar_untrack_keywords, and it declares the WRITE nature up front.

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 supplies useful operational context (Indie plan required, authorized account or write-scoped API key, caller's workspace), but never states when to pick this over alternatives such as sonar_track_app or sonar_untrack_keywords. Usage is implied rather than routed.

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 readOnlyHint=false, so the safety profile is covered. The description adds real value beyond them: it names what is destroyed ('associated tracking data'), the plan gate (Indie, trial counts), and the auth/scope requirement — none of which the annotations 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?

Two sentences, zero filler. The 'WRITE tool' marker and the core verb are front-loaded, with prerequisites trailing. Nothing 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 single-parameter tool with no output schema and covered annotations, the description supplies purpose, plan gate, auth needs, and destruction scope. The only minor gap is whether untracking is reversible and how it relates to the underlying product record.

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 app_id description already warns it is a Sonar UUID and NOT a store id. The description text adds nothing about the parameter, so baseline 3 applies — 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+resource ('untrack an app and its associated tracking data') and scopes it to 'the caller's Sonar workspace', which cleanly separates it from the sibling write tools (delete_product, remove_competitor). An agent can tell what this does and what it operates on 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 prerequisites (Indie plan, authorized account or write-scoped API key), which is useful context for whether the call will succeed, but never states when to use this tool versus the nearby alternatives like sonar_delete_product or sonar_remove_competitor. Usage is implied rather than routed.

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 bar is lower; the description still adds real value by flagging it as a WRITE tool and disclosing the plan requirement and write-scope auth requirement. It does not explain the blast radius of untracking (e.g. whether tracked history/rankings are lost), which would push it to 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?

A single dense sentence-block with the safety-critical 'WRITE tool' prefix front-loaded, followed by mode selection, then prerequisites. No redundant or filler text.

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 and full schema coverage, the description supplies the mode contract, plan gate, and auth gate an agent needs. It stops short of describing the effect on existing tracked data, which is the one remaining behavioral gap.

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

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

Schema description coverage is 100% and the schema already documents the mutual exclusivity of `all` and `ids` plus the app UUID semantics. The description largely restates that exclusivity rule rather than adding new meaning, so baseline 3 is appropriate.

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

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

States a specific verb+resource with scope ('bulk-untrack keywords for an app'), immediately distinguishing it from the single-keyword sibling sonar_delete_tracked_keyword and from sonar_untrack_app. 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?

Clearly states the two invocation modes ('all: true' OR 'ids: [...]', exactly one) and the prerequisites (Indie plan, authorized account or API key with write scope). It does not explicitly contrast against the sibling single-delete tool, but the mode-selection guidance is unambiguous.

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.

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

Annotations already flag destructive=true, idempotent=true, and openWorld=true. The description goes beyond them by disclosing the critical whole-document semantic ('does not merge') and the auth requirement ('authorized Sonar account or a write-scope API key'), telling the agent exactly what gets destroyed. It stops short of 5 only because no rate limits or failure modes are described.

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 action, then the critical non-merge caveat, the review-visibility note, and the auth prerequisite. No filler and 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?

For a nested-object mutation tool with no output schema, the description covers the destructive whole-document semantics, the required authorization, and the post-call human-review consequence. Return details are unnecessary given the 'shows up immediately in Screenshot Studio' note, though error/partial-failure behavior is not addressed.

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 layout parameter's schema description already explains the full-replacement/non-merge behavior and the placeholder caveat. The description's 'whole-document replace' phrasing reinforces but does not add meaning 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 ('Replace'), resource ('one screen's layout'), and scope ('in a screenshot set'), which cleanly distinguishes it from sonar_update_screenshot_set and sonar_add_screenshot. 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?

Provides a clear workflow ('fetch the current layout, modify it, send it back') that tells the agent how to invoke it correctly. It does not, however, explicitly name alternatives such as update_screenshot_set versus add_screenshot or state when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses the auth requirement (authorized account or write-scope API key) and the return shape (updated set with image data stripped). It does not surface that replacing the locale list destroys removed translations, but that detail lives in the schema.

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

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

Three tightly packed sentences that front-load the operations, then the return value, then the auth prerequisite. Every sentence carries information and nothing is padded.

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

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

With no output schema, the description correctly supplies the return-value contract ('updated set with image data stripped'), and it also states the auth requirement. Partial-update semantics are implied by 'and/or'. Minor gaps remain around whether unspecified fields are left untouched, but overall this is complete enough to call correctly.

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

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

Schema description coverage is 100%, so every parameter (name, set_id, locales, screen_order) is already documented, including the loss-of-translations warning on locales. The description names the three updatable areas but adds no syntax, format, or constraint detail beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states a concrete verb+resource (update a screenshot set) and enumerates the three specific mutations it can perform: rename, replace the extra-locale list, and reorder screens. This is unambiguous, but it does not differentiate from the singular sibling sonar_update_screenshot or sonar_set_screenshot_translations, so it stays at 4 rather than 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?

The 'and/or' phrasing implies this is a partial-update tool where any subset of fields may be supplied, which hints at when to use it. However there is no explicit when-to-use, no when-not-to-use, and no routing to alternatives such as sonar_set_screenshot_translations (which handles translation content) or sonar_update_screenshot (singular).

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