sonar

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

The description adds significant value beyond the annotations. It discloses the auth requirement (write-scope), ordering behavior (append at end), and the option to reorder via a sibling tool. Annotations only provide boolean hints (readOnlyHint=false, destructiveHint=false), so the description carries the full burden of behavioral disclosure and does so clearly.

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 two sentences, front-loaded with the primary action, and each sentence adds crucial information (purpose, ordering, auth requirement). There is no wasted text; it is a model of conciseness.

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 purpose, ordering, and auth. It does not describe the return value (no output schema) or the structure of the layout object, but the latter is partially handled by the schema and the sibling tool sonar_screenshot_layout_guide. For a simple append operation, the description is mostly complete, though a note about the layout guide would improve 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 the baseline is 3. The description does not add meaning beyond the schema: it mentions 'append a screen' but doesn't elaborate on the structure of the 'layout' object or the format of 'set_id'. The parameter information in the description is essentially redundant with the schema.

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

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

The description uses the specific verb 'append' and resource 'screen to a screenshot set', clearly distinguishing it from sibling tools like sonar_update_screenshot (update) or sonar_delete_screenshot (delete). The additional note about ordering ('at the end') and a sibling for reordering further clarifies the tool's unique role.

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 explicitly states a prerequisite ('Requires a write-scope API key') and gives an alternative for reordering ('reorder with sonar_update_screenshot_set'). It implies the tool is for adding new screens rather than modifying existing ones, though it does not exhaustively list when not to use it.

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

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

With only readOnlyHint:true in annotations, the description carries full weight and exceeds expectations by disclosing the feed's identity (same as the in-app Recent Alerts panel and email digest), the once-daily detection cadence, the type-specific payload shape (app/keyword names, old vs. new values), and the dependency on enabled alert rules. This gives the agent a realistic model of data freshness and availability that annotations could never 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?

Every clause is information-dense and earns its place, but the entire description is essentially one 80-word run-on sentence held together by colons and em-dashes. It would benefit from breaking into 2-3 sentences to improve scannability, though the front-loading is decent since it leads with the core resource and ordering.

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 and only minimal annotations, the description covers an impressive amount of necessary ground: what the payloads contain, when data becomes available (once daily), prerequisites (alert rules enabled), ordering semantics, and authentication requirements (Indie plan). This is nearly complete for an agent to use the tool effectively without additional discovery.

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 input schema provides 100% param coverage with clear documentation (enum values for type, 1-200 and default 50 for limit, ISO 8601 format with examples for since, and filtering semantics for app_id), which holds the baseline at 3. The description adds only marginal param value beyond the schema, such as reinforcing the since polling pattern ('Use your last poll time to fetch only new events' in the schema vs. 'Poll with since' in the description). No contradictions, but no meaningful semantic lift either.

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 (workspace alert events), the ordering (newest first), and enumerates the distinct event types (rank drops/gains, top-10 entries/exits, rating drops, etc.), which effectively differentiates it from sibling alert tools. It loses a point because the lead is a noun phrase ('The detected alert events for your workspace') rather than an explicit imperative verb+resource construction like 'Lists the alert events...', making the invocation intent slightly less immediate.

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 provides strong contextual guidance: events only exist for alert types with enabled rules (referencing sonar_set_alert), detection runs once daily (setting cadence expectations), and it prescribes the 'Poll with since' pattern for programmatic reaction. It also flags the Indie-plan requirement as a prerequisite. However, it never explicitly names an alternative tool for when NOT to use this one, missing the chance to contrast with siblings like sonar_list_alerts or the alert configuration tools.

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

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

Annotations already indicate readOnlyHint=false, but the description goes further by labeling the tool 'WRITE tool', detailing the generation/diff behavior, the 7-day cooldown, rate-limiting (429), and access requirements (paid plan, write scope). This adds significant context beyond the annotations without contradicting them.

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 not overly long, front-loading the 'WRITE tool' label and core function. Each sentence adds value: generation, clustering, narratives, diff, rate limit, alternative tool, and requirements. It could be slightly more streamlined, but it's well-structured and scannable.

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

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

Given the absence of an output schema, the description does well by summarizing what the tool produces (themes, narratives, diff) and covering rate limits, alternatives, and prerequisites. It doesn't specify the exact return format, but it's sufficient for a complex generative tool with a clear usage pattern.

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 single parameter app_id is fully described in the schema (including that it must be your own tracked app, not a store or competitor ID). The description reinforces this 'your own apps' requirement but does not add new semantic details beyond the schema, so it meets the baseline for 100% schema coverage.

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 generates a fresh AI competitive insight for your own app, clustering keyword gaps into opportunity themes, writing threat narratives, and diffing against previous analysis. It distinguishes itself from the sibling tool sonar_competitor_landscape by explicitly contrasting read vs. write behavior.

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 provides when to use: at most one analysis per app per 7 days, and directs users to sonar_competitor_landscape to read the current analysis. Also outlines prerequisites (paid Indie plan, write-scope API key) and the 429 cooldown behavior, giving clear guidance on alternatives and constraints.

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 provide readOnlyHint=true, and the description adds behavioral context: it works without an API key, has a free tier, and daily usage limits per IP. This goes beyond the annotations. However, it does not disclose what happens on rate limit excess or whether external API calls are made, leaving some gaps.

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 two sentences: the first clearly states purpose and output, the second adds usage context. Every sentence is valuable, no wasted words, and the most important information is 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?

For a simple read-only tool with three parameters and no output schema, the description adequately explains the return value (score plus itemized breakdown) and free tier usage constraints. It could mention error handling or rate limit specifics, but is largely complete for typical use.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (store, country, store_id) with descriptions. The description adds no additional semantics or syntax details beyond what the schema provides, so a 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 clearly states the tool calculates an ASO audit score (0-100) for an app and returns the overall score plus an itemized breakdown. It specifies the verb (calculate) and resource (app), and distinguishes from siblings by being the only scoring tool among many other sonar tools.

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

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

The description mentions it works without an API key with a free tier and limited daily use per IP, implying usage is free but rate-limited. However, it does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or prerequisites. Usage is implied but not fully guided.

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 readOnlyHint annotation already indicates the tool is safe and non-destructive. The description adds critical behavioral context beyond that: it lists exactly what types of changes are tracked (releases, metadata, screenshots, price, category), the ordering ('newest first'), and the plan requirement. This fully discloses the tool's behavior without contradicting 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?

The description is extremely concise at three sentences, each serving a distinct purpose: stating what the tool returns (first sentence), suggesting when to use it (second sentence), and noting prerequisites (third sentence). There is zero wasted text, and the structure is effective for quick understanding.

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

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

Given the tool has 3 parameters (all documented in schema), no output schema, and the annotations indicate read-only, the description covers the key aspects: what changes are tracked, ordering, plan requirement, and parameter clarification. It lacks explicit guidance on pagination or the response format, but for a tool with simple parameters and clear purpose, it is sufficiently 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%, so each parameter is documented in the schema. The description adds meaning by clarifying that 'app_id' is specifically 'Sonar app UUID — the id returned by sonar_list_apps or sonar_create_product. NOT a store id', which prevents misuse. It also explains the 'type' filter without repeating the enum, but does not elaborate on 'limit' beyond what the schema provides. Overall, it adds value to the schema but could be slightly more detailed.

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 returns 'Change history for a tracked app' and enumerates the specific change types: 'detected releases, metadata edits, screenshot swaps, price changes, and category moves, newest first'. This distinguishes it from sibling tools like sonar_app_lookup (current state) or sonar_app_rankings (rank history), making the purpose unambiguous.

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

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

The description explicitly says 'Useful for correlating rank movements with what the app (or a competitor) changed', which gives clear context for when to invoke this tool. It also mentions a plan requirement ('Requires an Indie plan (trial counts)'), adding important usage constraints. However, it does not explicitly state when NOT to use it or name alternative tools for related needs, missing the highest score.

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

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

Annotations already mark the tool as readOnlyHint=true, so the agent knows it's a safe read operation. The description adds value by disclosing the important constraint about free tier usage ('Works without an API key, limited daily use per IP'), which is critical for the agent to manage expectations and avoid surprising limitations. 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 two sentences and 33 words—extremely concise with zero filler. Every sentence adds vital information: the first states what it does, the second states when to use it and an important behavioral note.

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 could help by hinting at what the response includes (e.g., a list of keywords with scores). It does not do this, leaving the agent to guess the return format. However, for a simple extraction tool with 100% schema coverage and a readOnlyHint, this is a minor gap.

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

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

Schema description coverage is 100% and each parameter has a clear description in the schema (e.g., 'store' lists enum values, 'store_id' explains the format). However, the tool description itself adds no additional semantic nuance about the parameters—it does not clarify how 'max' relates to the output, or how 'country' affects keyword extraction.

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 verb ('Extract'), the resource ('keywords from an app's title and description'), and the output ('ranked by relevance'). It distinguishes itself from siblings like sonar_app_keywords (which likely retrieves tracked keywords) by emphasizing this is about extracting target keywords from the app's metadata.

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 explicitly states the use case ('understanding what an app... is optimizing for'), which implies competitive analysis. It does not mention specific alternatives from the sibling list (e.g., sonar_app_keywords, sonar_keyword_metrics) for when you should use a different tool instead.

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 annotation readOnlyHint=true already signals a safe read operation. The description adds significant behavioral context beyond this: cursor-paginated with default 50 per page, requires an Indie plan, and returns specific data fields including IDs for other tools. This is rich transparency that goes well beyond what annotations alone provide. The only minor gap is no explicit mention of idempotency or rate limits, but the plan requirement and pagination details are sufficient for a read 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 with no wasted words. First sentence establishes core purpose and returned data. Second sentence links to sibling tools for workflow continuity. Third sentence covers pagination and plan requirements. Each sentence serves a distinct purpose, and critical information is 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 that there is no output schema, the description compensates by listing the specific fields returned (difficulty, popularity, results count, note, starred_at) and the types of IDs (tracked-keyword ids and keyword_ids). With 3 params at 100% schema coverage, readOnlyHint annotation, and an output format described, the description is fully adequate for an agent to use this tool correctly without 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 description coverage is 100%, so the baseline is 3. The description adds value by explaining how `app_id` links to other tools ('the `id` returned by sonar_list_apps or sonar_create_product. NOT a store id'), which helps avoid misuse. It also clarifies that `cursor` should be omitted for first page and that limit has a server default. While the schema already covers these basics, the tool-specific context is helpful.

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

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

The description uses specific verb-resource combinations: 'List the keywords tracked for an app' with explicit detail on returned fields (difficulty, popularity, results count, note, starred_at) and IDs used by companion tools. This clearly distinguishes it from sibling tools like sonar_keyword_search, sonar_keyword_suggestions, and sonar_app_extract_keywords, which serve different keyword-related purposes.

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 explicitly states when to use this tool (to view tracked keywords with latest metrics) and references sibling tools for related operations: 'used by sonar_update_keyword_note and sonar_star_keyword, and the keyword_ids used by sonar_keyword_rankings'. This provides clear integration context. Additionally, it mentions plan requirements ('Requires an Indie plan (trial counts)'), aiding in selection.

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 adds behavioral traits beyond the readOnlyHint annotation: it specifies the exact metadata fields returned (name, developer, category, rating, reviews, installs, price), the free tier requirement, and the per-IP daily limit. It does not detail error handling or response format, but the disclosed traits are valuable for agent decision-making.

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, all front-loaded with the most important information first. Every sentence provides essential context: what it does, what it returns, and the notable free tier condition. No unnecessary words 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?

Given the tool's low complexity (3 parameters, no output schema) and the presence of annotations, the description is fairly complete. It covers the lookup purpose, return fields, and usage constraints. It does not describe the exact response structure, but the listed fields give sufficient guidance for an agent to interpret the output. The free tier note addresses a critical behavioral aspect.

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, the baseline is 3. The description adds value by explaining the overall purpose of the parameters (lookup by store ID) and listing the returned metadata fields, which helps the agent understand what the parameters will produce. It also notes the free tier limitation, which is not in the schema.

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

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

The description explicitly states 'Look up a single app by its store ID', using a specific verb and resource. It clearly distinguishes from sibling tools like sonar_app_search (search) and sonar_list_apps (list) by focusing on a single app lookup by store ID. The inclusion of the free tier note adds unique context.

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 when you have a store ID and want metadata, but it does not explicitly state when to use this tool versus alternatives such as sonar_get_app or sonar_app_search. No exclusion criteria or alternative tool names are mentioned. The free tier note is a constraint, not a usage guideline.

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

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

Annotations already mark the operation as read-only, and the description adds useful behavioral context: it is a computed/aggregate scoreboard, returns deltas and trends, works in a single call, and requires an Indie plan. No contradiction exists between the description and the readOnlyHint annotation.

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 detailed but stays on-topic and front-loads the core concept. Every clause contributes useful information about what the result includes, when to call it, or plan requirements. The long listing of output components is justified because there is no output schema to carry that 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?

Given there is no output schema, the description does a good job enumerating the returned dimensions: 7-day deltas, spark data, top-10 keywords, rank distribution, and opportunity types. It also covers plan constraints and the recommendation to call this before computing from raw history. A small gap is not describing how errors or untracked apps are surfaced, but overall it is 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 description coverage is 100%, so the schema already thoroughly documents both `app_id` and `days`, including that `app_id` is not a store id. The description itself adds little parameter-level detail beyond restating that the tool targets one of your own apps, so it meets the baseline without meaningfully extending the schema.

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

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

The description uses a specific, descriptive framing: a dashboard scoreboard for one app, listing exact metrics (visibility index, share of voice, keyword counts, rank distribution, opportunities). It clearly distinguishes this from raw rank-history tools by stating it returns the same computed numbers the dashboard renders, making its purpose unmistakable.

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 when-to-use guidance: 'Read this FIRST when asked how an app is doing.' It also provides a when-not-to guidance by saying you don't need to recompute from raw rank history. It does not name specific sibling alternatives, but the context is clear enough for an agent to route to this tool appropriately.

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 readOnlyHint annotation is present, and the description reinforces this by stating it provides 'rank history' – a read operation. It adds behavioral details beyond annotations: pagination over keywords, daily ranks, and plan requirement. No contradictions found.

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 extremely concise (3 sentences) yet packs crucial information: the resource (rank history), output structure (one array per keyword), use cases, pagination, and plan requirement. Every sentence earns its place with no fluff.

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

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

Given the 5 parameters, 100% schema coverage, and readOnly annotation, the description covers all key aspects: purpose, usage in context, pagination, parameter semantics, and access requirements. No output schema exists, but the description clarifies return shape ('daily ranks', 'one history array per keyword'). Complete for this tool's complexity.

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

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

Schema description coverage is 100% with detailed parameter descriptions (e.g., app_id is NOT a store id, cursor is from previous call's next_cursor). The description adds useful semantic guidance: 'restrict to one keyword' for keyword_id, and the mention of 'default 50 per page' complements the limit parameter but doesn't repeat schema. Value for parameters is high.

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 it provides 'rank history for an app's tracked keywords' with daily ranks over a requested window, one history per keyword. This uniquely identifies it among siblings like sonar_app_reviews, sonar_keyword_rankings, and sonar_app_changes, as it focuses specifically on rank history per keyword.

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 explicitly states when to use this tool: 'to check how rankings moved after a metadata change or to find keywords trending up or down'. It also describes pagination (cursor-paginated, default 50 per page) and a prerequisite (requires an Indie plan, trial counts), which helps the agent understand context and limitations.

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, so the safety profile is clear. The description adds value by disclosing the output structure (dollar estimate, confidence grade with factors, methodology) and instructing to always communicate confidence alongside the number. No contradictions 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 two sentences long and front-loaded with the core purpose. Every sentence adds distinct information: the first covers what and how, the second covers output and usage guidance. 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?

Given the simple input (3 params, 2 required, no output schema, no nested objects), the description adequately covers purpose, inputs, and output structure. A minor gap is not specifying edge cases (e.g., missing data leading to low confidence), but overall sufficient for an estimation tool.

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

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

Schema coverage is 100%, so all parameters are documented in the schema. The description does not add new parameter-level details beyond what the schema provides (store, store_id, country). Baseline 3 is appropriate given high schema coverage.

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 explicitly states 'Estimate monthly revenue for an app, based on install counts, ratings, and category benchmarks', providing a specific verb ('estimate'), resource ('revenue'), and key inputs. It clearly distinguishes from sibling tools like sonar_app_keywords or sonar_app_reviews, which focus on different app 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?

The description implies when to use this tool (when needing revenue estimates) and emphasizes communicating confidence. However, it does not explicitly exclude when not to use it (e.g., for very new apps with no data) or suggest alternative tools for similar tasks.

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, so this is a non-destructive read operation. The description does not contradict this and adds transparent context about the data being reviews (textual content with ratings). However, it does not disclose potential pagination behavior, rate limits, or whether the data is live vs cached, so some behavioral gaps remain.

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 extremely concise at just two sentences. The first sentence defines the core action and the second sentence lists clear, high-level use cases. Every word earns its place with zero 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?

Given the full schema (100% description coverage, enums, 7 well-documented params) and the readOnlyHint annotation, the description is largely complete for a list/fetch tool. It could optionally mention what the return value looks like, but since no output schema is defined, a minor expectation gap exists. Still, for its complexity level, it is thorough.

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 7 parameters are already documented in the input schema with descriptions and constraints (enums, min/max, defaults). The description adds marginal value beyond the schema by tying the parameters to the tool's purpose (filtering by star rating, sorting), but does not provide new semantic context. Baseline score 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 clearly states the action ('Fetch user reviews'), the target resource ('for an app'), and the key capabilities (filtering by star rating, sorting). It also provides use cases (sentiment analysis, feature-request mining, competitive research), which strongly differentiates it from siblings like sonar_app_changes 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 clear context for when to use the tool (sentiment analysis, feature-request mining, competitive research). However, it does not explicitly specify when NOT to use it or mention alternatives among the many sibling tools.

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

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

The description adds significant behavioral context beyond annotations: it confirms non-destructive read-only search (aligning with readOnlyHint), reveals that results are returned in store ranking order, and transparently states the free tier has limited daily use per IP. This provides concrete operational information an agent needs. 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 exceptionally concise: three sentences with zero waste. The first sentence states the core action, the second adds a key behavioral detail (ranking order), and the third provides important operational constraint (free tier limits). Perfectly front-loaded and 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 search tool with no output schema and good schema coverage, the description is complete enough. It covers supported stores, result ordering, and rate-limiting context. It misses mentioning what the output looks like (e.g., includes app IDs, icons, etc.), but since the output format is implied by 'metadata' and agents can infer from context, this is acceptable. With sibling tools, it could note alternatives for detailed app info (like sonar_app_lookup), but not required for completeness.

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 input schema covers all 4 parameters with individual descriptions (100% coverage). The description adds minimal extra meaning: it mentions the store parameter conceptually ('App Store or Google Play') and provides an example keyword, but this largely echoes the schema. Given full schema coverage, a baseline of 3 is appropriate for not going beyond.

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 verb 'Search apps' with the specific resource 'App Store or Google Play by keyword'. It distinguishes itself from sibling tools by focusing on search across stores, which is unique among the listed siblings that target specific apps, screenshots, keywords, or analytics. However, it could be clearer about how it differs from 'sonar_keyword_search' and 'sonar_keyword_suggestions', but overall it's specific and functional.

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 for general app discovery by keyword. It mentions results are in store ranking order, which hints at when to use it (for standard ranking). However, it provides no explicit guidance on when not to use it or alternatives among the many sibling tools (e.g., for detailed analytics, competitor analysis, or lookup of a specific app). The context about free tier and daily limits is operational but not comparative.

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 annotation, the description adds recency (last 7 days), pagination details (cursor-paginated, default 50), and a plan requirement (Indie plan). This provides meaningful behavioral context that goes beyond the annotation's simple read-only flag.

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

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

Three sentences, front-loaded with the core purpose, no superfluous text. Every sentence adds essential information (purpose, gap analysis, pagination, plan requirement).

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 is provided, so the description must convey what the response contains. It mentions keywords with difficulty and popularity and the gap marker, but does not list other fields like rank position, search volume, or the structure of pagination metadata. Adequate but not 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 coverage is 100%. The description adds semantic value by explaining that competitor_app_id comes from specific previous tool calls and that own_app_id triggers gap markers. This enhances understanding beyond the parameter descriptions in the schema.

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

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

The description clearly states the tool returns keywords a tracked competitor currently ranks for, including difficulty and popularity. It also highlights the gap analysis feature when passing own_app_id. This distinguishes it from siblings like sonar_app_keywords (own keywords) and sonar_keyword_rankings (general rankings).

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 own_app_id for gap analysis and notes the 7-day data window and pagination. It implies the tool is for competitor keyword analysis but does not explicitly exclude alternative tools like sonar_analyze_competitors or sonar_scan_competitor.

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 (safe read). The description adds value by disclosing that the AI insight is optional ('if one was generated') and describes the nature of the output data. It avoids contradictions and provides enough behavioral context beyond the annotations.

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

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

The description is a single, well-organized paragraph of about four sentences. It front-loads the core value proposition, then details the outputs, adds usage guidance, and notes the plan requirement. Every sentence earns its place with zero fluff.

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

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

Despite having no output schema, the description thoroughly enumerates the return values: stat categories, top rows with metrics, and AI insight structure. Combined with strong parameter semantics and annotations, it provides a complete mental model for the agent to invoke and interpret 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 description adds significant meaning: it clarifies that app_id must be 'YOUR OWN tracked app' from sonar_list_apps, and explicitly says 'NOT a store id, NOT a competitor id.' This prevents misuse beyond what the raw schema provides.

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 provides 'the full competitive keyword picture for one of your own apps vs every tracked competitor, in one call.' It then spells out the exact outputs (live stats, top rows, AI insight). This distinguishes it from simpler siblings (e.g., sonar_competitor_keywords) by emphasizing its comprehensive, consolidated nature.

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 instructs users to 'Read this before deciding which keywords to target next,' establishing a clear when-to-use context. It also notes the prerequisite 'Requires an Indie plan (trial counts).' While it does not explicitly list alternative tools for when not to use it, the guidance is strong enough to steer initial decision-making.

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 begins with 'WRITE tool', clearly labeling the operation type. Annotations show readOnlyHint=false, destructiveHint=false, and idempotentHint=false, which are consistent with a state-changing creation tool. The description adds value by naming the required plan tier and API scope, going 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 long, each serving a distinct purpose: labeling as write tool, defining a product, and noting return values and prerequisites. Slightly dense but no fluff. Could be more compact by merging the first two 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?

Given there is no output schema, the description compensates well by naming the returned values (product id and Sonar app ids). It also explains the cross-store product concept, which is critical domain knowledge. The only minor gap is not explaining what happens if the product already exists or what errors may occur, but the schema and annotations are otherwise adequate.

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. The description does not add parameter-level details beyond what the schema already documents (apps array with store, store_id, country; optional name). It doesn't elaborate on formats or defaults in a way that surpasses the schema, so it stays at 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?

The description clearly states 'creates a product in the caller's Sonar workspace and starts tracking the given app(s)'. It defines what a product is (cross-store unit of iOS/Android apps) and distinguishes this creation action from the many sibling tools like sonar_delete_product, sonar_track_app, or sonar_list_products.

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 explicitly notes the requirement for an Indie plan (trial counts) and an API key with write scope. It also explains that the returned product id and Sonar app ids are needed by two other tools (sonar_track_keywords and sonar_track_competitor), providing context for when to use this tool. No explicit when-not alternatives are given, but the purpose and prerequisites are 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?

The description adds value beyond annotations: it mentions 'Requires a write-scope API key' (auth requirement) and states 'The set is immediately visible/editable for humans in the Screenshot Studio (studio_url in the response).' These details reveal behavioral traits like persistence and immediate availability. No contradiction with annotations (readOnlyHint=false, destructiveHint=false).

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

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

The description is three sentences long, front-loaded with the core purpose in the first sentence. The second sentence provides a key prerequisite, and the third sentence covers both immediate effect and authentication. Every sentence is necessary and no words are 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?

Given the tool has 6 parameters (3 required) and no output schema, the description covers what the tool does, prerequisites, immediate effect, and auth requirements. It mentions the studio_url in the response but does not detail the full response structure or error/validation conditions. For a creation tool, it is largely complete, but could a bit more about potential failure modes or output 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?

While schema coverage is 100% (baseline 3), the description adds meaningful extra guidance: for the 'screens' parameter it explains the need to read the layout guide first and clarifies that 'Either this or template_id, not both; with neither you get one blank screen.' For 'device_size' it provides an example ('iphone-6.7') and references the sonar_screenshot_devices tool. This surpasses the schema's raw 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 begins with 'Create an app-store screenshot set for a product,' which clearly states the verb (create) and resource (screenshot set). It distinguishes this from sibling tools like sonar_add_screenshot, sonar_list_screenshot_sets, sonar_update_screenshot_set, and sonar_delete_screenshot_set by focusing on initial creation and referencing the prerequisite guide.

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 instructs users to 'Read sonar_screenshot_layout_guide first, then author the screens array,' providing a clear prerequisite for correct usage. It also notes the immediate visibility in Screenshot Studio, implying post-creation state. However, it does not explicitly state when not to use this tool (e.g., if updating an existing set, use sonar_update_screenshot_set instead).

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 adds 'WRITE tool' and mentions plan/scope requirements, which are beyond the annotations. It does not contradict annotations. The description could mention irreversibility but the annotations and verb 'delete' suffice. No annotation contradiction.

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 two sentences: the first states the action and type ('WRITE tool — delete...'), the second gives requirements. Every sentence is essential and there is no wasted text. It is front-loaded with the verb and tool type.

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

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

Given the tool has one parameter, no output schema, and annotations cover safety, the description adequately explains the action, prerequisites, and how to obtain the id. It does not describe the return value, but for a simple delete operation the agent can infer success/failure. The description is sufficient for a low-complexity 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 only parameter 'id' has a full schema description (100% coverage) that explains it is a UUID from sonar_list_alerts or sonar_set_alert. The tool description itself does not add any additional meaning beyond what the schema already provides. 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 clearly states the verb 'delete', the resource 'alert subscription', and the scope 'in the caller's Sonar workspace'. It distinguishes this from sibling tools like sonar_set_alert and sonar_list_alerts by specifying the deletion action. The title 'Delete Alert Rule' is slightly different but the description clarifies.

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 provides prerequisites (Indie plan, API key with write scope) which help the agent decide whether it can use the tool. It implies usage when the goal is to remove an alert subscription, but does not explicitly state when to use vs alternatives or when not to use it. The sibling list provides context, but the description itself lacks explicit exclusionary 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 readOnlyHint=false, so the description's 'WRITE tool' label is redundant. However, it does add valuable behavioral context about the side effect of untracking apps and the plan/scope requirements, which goes beyond annotations. No contradiction.

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 concise and front-loaded, with the essential info in the first sentence and additional requirements given succinctly in the second. Every sentence contributes value without fluff.

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

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

For a simple destructive tool with one parameter and no output schema, the description covers the purpose, side effects, and prerequisites. It could benefit from a note on what happens after deletion (e.g., irreversibility), but annotations already signal destructiveness, so this is adequate.

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

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

The schema already covers the single parameter product_id with a clear description, and schema description coverage is 100%. The description does not add anything new about the parameter (e.g., format or validation details), so it stays at the 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?

The description clearly states the action: 'delete a product and untrack its apps in the caller's Sonar workspace.' It specifies the resource (product) and the side effect (untracking apps), properly framing the tool as a WRITE/destructive operation in context.

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 mentions requirements (Indie plan, write scope) and explicitly labels it a 'WRITE tool', but does not provide explicit guidance on when NOT to use it or when to use alternative tools (e.g., sonar_delete_alert, sonar_untrack_app). The requirement is useful context but lacks exclusions or comparisons.

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 readOnlyHint=false, so the agent knows it's destructive. The description adds useful context that the last screen cannot be deleted and that a write-scope API key is required. This supplements the annotations without contradicting them.

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: states the action, adds a critical constraint, and notes the auth requirement. No filler, highly efficient.

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 a single parameter, full schema coverage, no output schema, and annotations already covering the destructive nature, the description adequately covers the key behaviors. It could optionally mention that the operation is idempotent (as hinted by idempotentHint), but that's already in annotations. Overall, sufficient for agent use.

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

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

Schema coverage is 100%, so the schema already documents the screenshot_id parameter. The description does not add extra meaning beyond what the schema's description ('Screen id to delete') provides. 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 clearly states it deletes one screen from a screenshot set, which distinguishes it from sibling tools like sonar_delete_screenshot_set and sonar_delete_product. The verb 'delete' plus the resource 'screen from a screenshot set' is specific and leaves little ambiguity.

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

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

The description notes that deleting the last screen is rejected, which provides an important constraint. However, it does not explicitly say when to use this tool versus alternatives like updating a screenshot set or adding a screenshot, nor does it mention prerequisites such as needing the screenshot set ID.

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

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

Annotations already mark the tool as destructive (destructiveHint: true) and not read-only (readOnlyHint: false). The description adds critical behavioral context beyond annotations by specifying exactly what gets destroyed ('screenshot set and everything in it (screens, translations)'), emphasizing irreversibility, and noting authentication requirements ('write-scope API key'). No contradictions.

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 concise at two sentences with zero wasted words. Critical information (purpose, scope, irreversibility, user confirmation requirement, auth scope) is front-loaded in the first sentence, making it easy for an AI agent to quickly extract key decision-making facts.

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

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

Given the tool has only one parameter, no output schema, and annotations already provide destructive and idempotent hints, the description is complete. It covers the action, permanent impact, user deliberation necessity, and auth requirements—leaving no gaps for an agent to safely invoke this high-risk tool.

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

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

Schema description coverage is 100% with only one required parameter (set_id), which the schema already documents as 'Screenshot set id.' The description does not add new semantic meaning beyond what the schema provides, so a baseline score 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 clearly states the verb 'permanently delete' and the target resource 'screenshot set and everything in it (screens, translations)', which matches the tool name and distinguishes it from sibling tools like sonar_delete_screenshot (which targets individual screenshots) and sonar_delete_product (which targets products).

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 explicitly warns that the action is irreversible and instructs the agent to 'confirm with the user before deleting work they may want', providing clear when-to-use guidance and cautioning against misuse. It also notes the requirement for a 'write-scope API key', which differentiates it from read-only operations.

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 provide destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds valuable context beyond these: it explicitly labels the tool as a 'WRITE tool', states the need for an Indie plan (trial counts) and a write-scoped API key, and clarifies the id source. No contradiction with annotations; the additional details help the agent understand authorization and constraints.

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 extremely concise: exactly two sentences with no redundant information. It front-loads the purpose and follows with the requirements. Every sentence adds essential value—purpose, identification method, and prerequisites. 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?

Given the tool's simplicity (one parameter, no output schema, but with annotations), the description is largely complete. It covers the action, the identifier, the plan requirement, and the API key scope. It does not describe the return value or error cases, but since there is no output schema, this is acceptable. The only minor gap is the lack of explicit mention of what happens if the id doesn't exist, but idempotency implies it's safe. Overall, it provides enough context for correct invocation.

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 input schema covers 100% of the single parameter with a clear description in the schema itself. The tool description repeats that the id comes from sonar_app_keywords and is not the keyword_id, which adds minimal value over the schema. The baseline is appropriate since the schema does the heavy lifting, and the description adds only slight reinforcement.

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's purpose: 'stop tracking one keyword/app pair' using the tracked-keyword id. It specifies the action (delete/stop tracking), the resource (tracked keyword), and the context (caller's Sonar workspace). It distinguishes from sibling tools like sonar_untrack_keywords by focusing on a single pair identified by a specific ID, and from sonar_delete_alert by targeting a different entity.

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 provides clear context on when to use this tool: to stop tracking a single keyword/app pair identified by a tracked-keyword id from sonar_app_keywords. It also states prerequisites (Indie plan, write-scoped API key). It does not explicitly mention alternatives (e.g., bulk deletion via sonar_untrack_keywords) but the singular focus and ID source effectively imply the usage scope.

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, so the description doesn't need to restate that. It adds useful behavioral context: results are limited to tracked apps, keywords are not yet tracked, rows are classified into buckets, and results are ordered by an opportunity score (0-100, best first). It also discloses the plan requirement, which is valuable operational information.

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 deliver the core value proposition, result categories, key metrics, ordering, and the recommended next action. There is no filler, and the plan requirement is included without bloating the text. Every clause adds information.

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

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

With no output schema, the description compensates by naming the returned fields (popularity, difficulty, AI relevance, opportunity score) and the ordering. It also gives a complete workflow: read this list, pick winners, track them. It doesn't mention default filters or pagination, but the parameter schema covers those, and the read-only annotation covers the safety profile.

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 input schema covers all 8 parameters with full descriptions and enum values at 100% coverage, so the schema already handles parameter semantics. The description adds context about returned fields like opportunity score but doesn't need to repeat individual parameter docs. Baseline 3 is appropriate because 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?

The description clearly states this returns discovered, untracked keywords from Sonar's discovery engine for tracked apps, with specific categories (ranked finds, competitor gaps, AI/autocomplete ideas) and metrics. It distances itself from generic keyword tools by positioning it as the 'what should I track next' list and references the natural follow-up tool.

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

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

It explicitly says when to use this tool: as the discovery/next-tracking decision source, and directs the user to sonar_track_keywords for the next step. It also notes the Indie plan requirement. It doesn't explicitly compare against related keyword-research siblings like sonar_keyword_suggestions or sonar_competitor_keywords, so it misses the full when-not-to-use guidance.

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

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

The description truthfully discloses that the tool writes ZIP files to the filesystem, but the annotation declares readOnlyHint=true, which directly contradicts this write behavior. Since the description contradicts the annotation, a score of 1 is mandated per rubric rules.

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

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

Three sentences with front-loaded action ('Render... save...'), no fluff. Every sentence earns its place: main operation, engine identity, and transport guidance. Efficient and scannable.

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 core functionality, usage location, and rendering engine well. However, the description omits return values (no output schema exists) and error handling. Combined with the annotation contradiction, the agent may be misled about safety. Adequate but has clear gaps.

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%, baseline 3. The description adds valuable meaning: it explains how locales and all_locales interact ('Omit together with all_locales for source-only'), names the ZIP file pattern (<locale>.zip), and clarifies output_dir behavior ('created if missing'). This goes beyond the schema's bare 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 specifies the verb ('Render... and save'), resource ('screenshot set to store-ready PNGs'), and output ('one ZIP per locale'). It distinguishes itself from siblings like sonar_get_screenshot_set by focusing on export to filesystem, and explicitly mentions target stores (App Store Connect / Play Console).

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 states when to use this tool ('local stdio use') and when not to ('over the hosted transport call GET /api/v1/screenshots/sets/:id/export directly instead'). This provides clear context and alternatives, leaving no ambiguity about transport restrictions.

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?

While annotations already indicate a non-read, non-idempotent write operation, the description adds important behavioral details: cooldown enforcement, error status 429 with next available time, minimum review count, and plan/scope requirements. It also labels the tool as 'WRITE tool' at the start, reinforcing its mutating nature.

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 information-dense but efficient, front-loading the tool's purpose and write classification. Every clause adds necessary operational detail (cooldown, minimum reviews, auth requirements, alternative read tool) without fluff or repetition.

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

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

For a write/generation tool with no output schema, the description explains what the tool produces, under what conditions it can run, its rate limits, error behavior, and prerequisite access requirements. The mention of alternative read tool also completes the workflow context.

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

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

Schema description coverage is 100%, so the schema already explains app_id and country clearly. The description adds the behavioral context that insights are per app+country and cooldown applies to that combination, but it does not substantially add new parameter meaning beyond the schema.

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

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

The description clearly states the tool's action: it generates a fresh AI review analysis for a tracked app from recent reviews, listing concrete output themes. It also distinguishes itself from the sibling read tool sonar_review_insights by explicitly saying the current analysis should be read there.

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 explicit usage context: one analysis per app+country every 90 days, 429 cooldown behavior, minimum 5 recent reviews required, and paid-plan/write-scope prerequisites. It explicitly directs users to sonar_review_insights when they need to read the current analysis, making the alternative 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=true, so the description adds value by specifying the data scope (up to 90 daily snapshots of specific metrics) and the plan requirement. This is beyond what annotations provide, giving the agent useful behavioral context without contradiction.

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 sentence states purpose and data scope; the second adds the plan requirement. No fluff, perfectly concise.

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

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

Given the tool's simplicity (one parameter, no output schema), the description fully covers what the tool does, what data it returns, and a key prerequisite. The schema and annotations handle the rest, leaving no gaps.

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 for app_id is already detailed (UUID from specific sources, not a store id). The description adds no additional parameter-level information beyond the schema, so a baseline score 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 clearly states it retrieves full details for one tracked app, including store metadata and up to 90 daily snapshots. This specific verb+resource pairing distinguishes it from sibling tools like sonar_list_apps (list) and sonar_track_app (create).

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 mentions a prerequisite (Indie plan), which helps the agent know when the tool is usable. However, it does not explicitly state when to use this vs alternatives or when not to use it. The context is clear but lacks exclusionary 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?

The annotation already sets readOnlyHint=true, so the description adds value by noting the default placeholder behavior for image data and that a layout with placeholders is rejected on update. This goes beyond annotations but doesn't detail other behavioral traits like auth requirements or rate limits, which are not covered by annotations either.

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 two sentences, front-loading the primary action and then clarifying a key behavioral option. The language is efficient, but the sentence about placeholders could be slightly tighter (e.g., 'By default, inline image data is replaced with placeholders for readability').

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

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

Given the tool's moderate complexity (2 params, no nested objects, no output schema to describe), the description effectively covers the core functionality and a critical behavioral nuance. It does not explain the return structure in detail, but the description implies it includes layout JSON and translation overrides, which is sufficient for this context.

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 reiterates the purpose of 'include_image_data' (default false, placeholder vs raw data), which adds some context but mostly mirrors the schema's description. No new semantics are added for 'set_id'.

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

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

The description uses specific verbs and nouns: 'Fetch a screenshot set in full', details what it returns ('layout JSON plus per-screen translation overrides keyed by locale'), and distinguishes itself from siblings like 'sonar_get_app' or 'sonar_update_screenshot_set' by specifying the read-only, comprehensive nature of the output.

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 provides clear context on when to use the tool, such as fetching full data for a screenshot set. However, it does not explicitly mention when not to use it or provide alternatives among the many screenshot-related siblings like 'sonar_list_screenshot_sets' or 'sonar_export_screenshots', which could guide selection more precisely.

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 annotation, the description discloses several non-obvious behaviors: pending results are queued on the scrape fleet and not charged, the tool waits and re-checks briefly, and callers must retry after retry_after_seconds if still pending. It also clarifies API-key vs free-tier behavior, adding real operational 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?

The description is dense but every sentence earns its place: core result, selection criteria, cost/auth constraints, sibling alternative, and async pending behavior. It is front-loaded with the most decision-relevant 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?

There is no output schema, so the description carries the burden of explaining what will come back—difficulty/popularity and pending/retry behavior—which it does. The simple parameter set and read-only annotation mean nothing essential is missing for a correct invocation.

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 input schema already documents store, country, keyword, and keywords thoroughly. The description adds pricing context (1 credit per keyword) and reinforces the bulk maximum, but does not materially change parameter semantics beyond the schema.

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

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

The description states exactly what the tool returns—difficulty and popularity for a keyword or up to 25 in bulk—and distinguishes it from sonar_keyword_search by noting it should not be used for related keyword ideas. This makes the tool's purpose unmistakable relative to its siblings.

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

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

It gives an explicit when-to-use condition ('already know which keywords you care about'), cost information, free-tier limits, and names sonar_keyword_search as the alternative when related keyword ideas are needed. This leaves no ambiguity about selection.

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 provide readOnlyHint=true, and the description aligns with that by describing a read-only historical query. The description adds value beyond annotations by specifying the ordering ('newest first'), the scope ('one tracked keyword'), and the plan requirement. No destructive behavior is implied, and the description reinforces the read-only nature.

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 concise at three sentences, each serving a distinct purpose: function, usage guidance, and prerequisites. The most critical information is front-loaded ('SERP history for one tracked keyword'), and there is no redundancy or fluff. 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?

The tool has only two parameters and no output schema. The description covers the return concept ('which apps ranked in the top results on each measured day') and ordering, but it does not specify the exact output format (e.g., array of objects with date, ranks, app identifiers). For a tool with no output schema, additional detail on the response structure would help agents parse results correctly. It is adequate but not 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%, with both parameters (keyword_id and days) clearly described in the schema. The tool's description does not add any additional parameter details beyond what the schema already provides. It reinforces that the keyword must be tracked, but that is implicit from the schema's 'keyword_id from sonar_app_keywords' hint. 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 clearly states the tool returns 'SERP history for one tracked keyword' with 'which apps ranked in the top results on each measured day, newest first.' It uses a specific verb ('get history') and resource ('keyword SERP rankings'), and the context of 'tracked keyword' distinguishes it from sibling tools like sonar_keyword_metrics (aggregate metrics) or sonar_keyword_search (search for 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 explicitly says 'Use this to see who competes on a keyword and how the top spots shifted over time.' It also provides prerequisites: 'The keyword must be tracked in the caller's Sonar workspace' and 'Requires an Indie plan (trial counts).' This gives clear context for when to use it, though it does not explicitly mention alternatives or when not to use it.

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

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

Annotations already declare readOnlyHint=true, so the description correctly implies no destructive behavior. It adds value by specifying the exact returned fields (difficulty, popularity, results count, autocomplete suggestions). However, it does not disclose any rate limits, authentication requirements, or potential side effects beyond what annotations provide, so a 3 is appropriate.

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 concise sentences with no wasted words. The first sentence states the purpose and output, the second gives usage guidance. 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?

With no output schema, the description adequately covers what is returned (difficulty, popularity, results count, autocomplete suggestions). It also explains the seed keyword concept. For a tool with three well-documented parameters, this is sufficient. A minor gap is not specifying the number of autocomplete suggestions or whether pagination exists, but overall it is complete enough.

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% because all three parameters have descriptions. The description adds no new parameter-specific information beyond what the schema provides; it only uses the term 'seed keyword' which matches the 'query' parameter. Baseline 3 is correct.

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

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

The description specifies the verb 'research' and the resource 'a keyword and related terms', and lists the return values (difficulty, popularity, results count, autocomplete suggestions). This distinguishes it from sibling tools like sonar_keyword_metrics (which likely returns only metrics) and sonar_keyword_suggestions (which may return only suggestions).

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 includes 'Use this to find keywords worth targeting.' which gives clear context for when to invoke the tool. However, it does not explicitly mention when NOT to use it or alternatives among the many sibling tools, 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 provide readOnlyHint=true, so the description need not reiterate non-destructiveness. It adds useful context: the tool is lighter/faster, works on free tier with daily limits per IP, and returns a priority score. A minor gap is not specifying the return format (e.g., list of terms with scores) 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?

Three short, information-dense sentences with no fluff. Every sentence adds value: core action, differentiation from sibling, and usage constraint (free tier). Front-loaded with the main purpose.

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

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

Given the tool's simplicity (3 params, no nested objects, no output schema), the description covers the core semantics, differentiation, and API key constraint. A minor gap is not describing the return format or the priority score range, but overall it's sufficient for an agent to decide and 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 description coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining what the output (priority score) means and the overall purpose of suggestions (autocomplete), justifying a 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?

The description uses a specific verb+resource ('Get autocomplete suggestions for a seed keyword') and explicitly differentiates from siblings ('Lighter and faster than sonar_keyword_search') and specifies the stores it covers (App Store, Google Play).

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 explicitly states when to use this tool vs sonar_keyword_search ('Lighter and faster... use when you only need term ideas without difficulty/popularity scoring'), and mentions it works without an API key (free tier, limited daily use per IP), providing an important constraint.

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 provide readOnlyHint: true. The description adds domain knowledge about what alert rules contain, but does not disclose additional behavioral traits such as pagination, rate limits, or data freshness. It does not contradict 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 sentences: first states the action and explains what alert rules are, second provides a prerequisite. No wasted words, front-loaded with the core purpose. Highly efficient.

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 parameters, no output schema, and annotations present, the description is fairly complete. It explains the tool's output and a key constraint. It could possibly hint at the output structure, but overall it's adequate for an agent to select and invoke the tool correctly.

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

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

There are no parameters, so schema coverage is 100%. The description adds value by explaining the meaning of the returned data (change type, scope, threshold, enabled). Baseline for 0 params is 4, which is appropriate here.

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

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

The description clearly states 'List your alert subscriptions' with a specific verb and resource. It explains what each rule defines (change type, scope, threshold, enabled), distinguishing it from sibling tools like sonar_set_alert and sonar_delete_alert. No ambiguity.

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

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

The description mentions a prerequisite ('Requires an Indie plan'), which is useful context, but it does not explicitly state when to use this tool versus alternatives or when not to use it. The purpose is clear but usage guidance is only implied.

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

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

Annotations provide readOnlyHint=true and title, which already indicate a safe read operation. The description adds the pagination behavior (cursor-based, default 100 per page) and the plan requirement (Indie plan/trial counts) – neither is deducible from annotations alone. The description does not contradict annotations. A 4 is warranted because while the description adds useful behavioral context, it doesn't detail what happens if the plan is exceeded or how cursors expire.

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 long, each carrying distinct value: what data is returned, how the results are used, and pagination/plan details. No wasted words. Front-loaded with the primary purpose.

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 that there is no output schema, the description compensates by naming the output fields (rating, review count, version, installs) and mentioning the pagination cursor. However, it does not fully describe the response shape (e.g., total count, error format) or the exact structure of each snapshot. It is nearly complete for a list tool, but lacks confirmation of whether all fields are always present.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by specifying the default page size (100) and that the cursor is obtained from a previous call's `next_cursor`. It also clarifies that omitting cursor fetches the first page. These semantic details go beyond the schema's generic descriptions. A 4 reflects the added context without being exceptional.

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

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

The description uses a clear verb ('List') and specific resource ('apps tracked in the caller's Sonar workspace') including what kinds of apps (own + competitors) and what data each comes with (latest snapshot fields: rating, review count, version, installs). This is easily distinguishable from the many sibling tools like sonar_get_app (single app) or sonar_track_app (adding tracking).

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 explicitly states that this tool returns the Sonar app UUIDs needed as input for four other tools (sonar_get_app, sonar_app_keywords, sonar_app_rankings, sonar_app_changes) and specifies that results are cursor-paginated with a default page size of 100. It also mentions the plan requirement (Indie plan or trial). No alternative tool is suggested for a different use case, but the dependency chain is exceptionally 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 mark the tool as read-only (readOnlyHint=true). The description goes beyond by revealing that the output includes linked store versions and competitor counts, and that a specific plan (Indie) is required. It also clarifies that trial counts count toward the requirement. No contradictions 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 two sentences, front-loading the core action and output in the first sentence, followed by usage guidance and constraints in the second. Every sentence adds value; there is no waste.

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 compensates by naming the key return fields (store versions, competitor counts, UUIDs). The tool is simple with no parameters, so the description covers essential aspects. A slightly fuller picture of output structure (e.g., array vs. object) could improve completeness, but the current version is adequate.

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

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

The tool has zero parameters, so schema coverage is effectively 100%. The description adds no parameter information because none is needed. Per the rubric, the baseline score for zero parameters 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?

The description uses the specific verb 'List' and identifies the resource as 'your products'. It elaborates on the content ('linked store versions and competitor counts') and provides a clear use case ('discover product/app UUIDs'). This strongly distinguishes the tool from sibling tools like sonar_list_apps, which likely lists apps separately.

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 explicitly states when to use the tool ('discover product/app UUIDs') and includes a prerequisite ('Requires an Indie plan'). It does not explicitly mention when not to use it or name alternatives, but given the tool's simplicity (no parameters), this level of guidance is clear and sufficient.

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. The description adds value by specifying that the tool returns only metadata fields (store, device size, locales, studio_url), which is consistent and provides helpful detail beyond the readonly annotation.

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 extremely concise with two sentences. The first sentence states the purpose and return fields, the second provides a usage alternative. 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?

Given the tool has only one parameter, no output schema, and annotations present, the description sufficiently covers what the tool does, what it returns, and when to use a sibling tool. It is complete for its complexity.

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

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

Schema description coverage is 100% for the sole parameter product_id, with a description that tells where to find it. The tool description does not add any further parameter semantics, so the baseline score 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 clearly states the tool lists a product's app-store screenshot sets and specifies it returns metadata only (store, device size, locales, studio_url). It explicitly distinguishes from sonar_get_screenshot_set for full layouts, making the purpose unambiguous.

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

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

The description provides guidance by telling the agent to use sonar_get_screenshot_set when full layouts are needed. It does not explicitly list when not to use this tool, but the alternative is clearly stated, offering sufficient context for selection.

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?

Given the readOnlyHint annotation, the description adds valuable context: it is a read-only aggregation call, and it explicitly mentions the 403 error for non-Agency plans. It also mentions it mirrors the /portfolio page, providing a reference for expected output. No contradictions.

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 a single but long paragraph; it is front-loaded with the key idea ('whole portfolio's health in one call') and then lists the contents efficiently. Every sentence adds value, though the enumeration is long but warranted given the breadth.

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

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

Given the tool's complexity (it aggregates many types of data), the description is fairly complete: it enumerates the key output sections, states the audience, and alerts to plan restrictions. Without an output schema, the enumeration is helpful. It could mention that results are not paginated or any size limits, but overall 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?

The tool has zero parameters, and the schema provides full coverage. The description adds meaning by detailing the content and scope of the result, which is the primary semantic value since there are no parameters to explain.

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 it provides a portfolio rollup for agencies, listing specific content (per-app KPIs, totals, keyword movers, triage, opportunities). It is distinct from sibling tools by aggregating across the entire portfolio, unlike per-app 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?

The description implies when to use it: for organizations managing many apps, and when a comprehensive portfolio-level view is needed. It also notes the requirement for an Agency plan, but does not explicitly contrast with alternatives like individual app tools.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds value by calling it a 'WRITE tool' and specifying the required plan and scope, which are behavioral constraints beyond what annotations convey. It does not contradict annotations. It could further disclose whether the removal is reversible or affects other data, but overall the transparency is good.

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 two sentences, front-loading the critical 'WRITE tool' label and immediately stating the action and scope. Every piece of information is necessary and no words are wasted. It is optimally concise for an AI agent to parse.

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 tool is simple (two required parameters, no output schema) and the description covers the action, requirements, and parameter sources. It does not describe the return value or confirm success/failure, but for a removal operation this is acceptable. The schema descriptions and annotations fill most gaps, making the definition sufficiently 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%, with both parameters (product_id, competitor_app_id) having clear, self-contained descriptions referencing other tools (e.g., 'sonar_list_products' for id). The tool's description does not add any additional parameter details beyond the schema, so a baseline score 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 clearly states the verb 'remove' and the resource 'a competitor from a product in the caller's Sonar workspace.' It explicitly labels itself as a 'WRITE tool,' which distinguishes it from read-only sibling tools like sonar_competitor_keywords or sonar_app_lookup. Compared to other competitor-related tools (e.g., sonar_track_competitor, sonar_scan_competitor), the purpose is unique and unambiguous.

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

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

The description provides usage context by stating it requires an 'Indie plan (trial counts)' and an 'API key with the write scope,' which informs prerequisites. However, it does not explicitly contrast with alternatives like sonar_untrack_app or sonar_delete_product, nor does it advise when not to use it. The action is self-explanatory, so the guidance is mostly adequate but lacks exclusions.

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

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

Annotations already declare readOnlyHint=true, lowering the burden, and the description adds genuine extras beyond that: the null-when-unavailable behavior, the plan gating ('Requires an Indie plan (trial counts)'), and the per-country generation context. It doesn't mention data freshness/recency or rate limits, which prevents a perfect score, but the high-value gotchas (plan, null case) are disclosed.

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

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

The core is a single dense sentence, front-loaded with the purpose ('The latest AI review analysis'), followed by a well-sequenced content list and then the operational notes. Every clause carries meaning and nothing is fluff. Slight deduction for the first sentence being a long wall of content that mixes output description and conditional behavior without line breaks.

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

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

With no output schema, the description carries the full burden of explaining return content, and it delivers: themes, quotes, trend movement, sentiment, feature requests, and what changed. It also handles the key failure mode (null insight → generate path) and the plan prerequisite. It's marginally short of a 5 only because it doesn't acknowledge the raw-reviews sibling or freshness of the analysis data.

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 per the rubric the baseline is 3 and the description need not add parameter details. The prose does reinforce app_id's scope ('your own or a competitor') but introduces no new parameter semantics beyond the schema. This matches the baseline exactly.

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

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

The description names a specific resource ('latest AI review analysis for a tracked app') with an array of concrete content details (themes with frequency, verbatim quotes, trend movement, sentiment, feature requests, deltas vs previous analysis). It explicitly scopes to 'your own or a competitor' app, and the pointer to sonar_generate_review_insights helps distinguish it from that sibling. Only minor weakness is the implicit verb, but the resource and scope are unmistakable.

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 an explicit conditional alternative: '`insight` is null if none has been generated yet — use sonar_generate_review_insights,' telling the agent exactly when to switch tools. The plan requirement also sets expectations. It loses a point because it never contrasts with the likely raw-data sibling (sonar_app_reviews) or other review-adjacent tools, leaving some differentiation implicit.

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

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

The description goes well beyond annotations: it reveals it is a write tool, outlines the scan workflow (generation, inline verification ~30s, background verification), and notes the returned counts. No contradictions 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 a single, well-structured paragraph of ~80 words. It front-loads the key action 'WRITE tool — runs an AI keyword discovery scan' and packs in behavioral, prerequisite, and follow-up information without waste.

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?

Without an output schema, the description covers return values (counts), timeline (inline ~30s, background hours), and references a sibling for reading results. Misses explicit error conditions but is adequate for the tool's complexity.

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 descriptions for each parameter. The main description adds context about the scan process but does not elaborate on parameter specifics beyond what the schema provides. 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 specifies the verb 'scan' and resource 'competitor' for AI keyword discovery. It clearly distinguishes from siblings like sonar_competitor_keywords (read results) and sonar_track_competitor (initial tracking).

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 states prerequisites (Indie plan, write scope) and directs users to read results via sonar_competitor_keywords. It implies when to use but does not explicitly exclude alternatives or give 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 provide readOnlyHint=true, so no contradiction. The description confirms it is a read-only listing operation by saying 'List the device sizes...'. It adds value by detailing what data is included (canvas dimensions, store), but does not describe output format or pagination, which is acceptable for a zero-parameter tool with 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?

The description is two sentences with no wasted words. The first sentence defines the tool's output, and the second sentence provides usage guidance. Every sentence serves a clear purpose.

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

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

Given the tool has no parameters, no output schema, and annotations already signal read-only, the description covers the key behavioral aspects. It explains what devices are listed and why the agent should call it. A minor gap is not mentioning that the output can be filtered or ordered, but since there are no parameters, this 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?

The input schema has zero parameters with 100% coverage, so there is nothing to compensate for. The description explains what the tool returns without needing to clarify parameters, earning a baseline above 3 by providing context about the returned data (canvas dimensions, store assignment).

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 lists supported device sizes for app-store screenshot sets, including canvas dimensions and store association. It distinguishes itself from siblings like sonar_list_screenshot_sets by focusing on device sizes rather than sets, and from sonar_create_screenshot_set by explicitly stating to pick a device here before creating a set.

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

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

The description explicitly guides the agent to use this tool before invoking sonar_create_screenshot_set, providing clear sequencing. It also implies this is a prerequisite step for screenshot set creation, which differentiates it from other listing tools in the sibling list.

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 provide readOnlyHint=true. The description adds behavioral context beyond that by stating it is a reference that documents the layout format, coordinate system, and workflow. There is no contradiction with annotations. The description covers the tool's read-only nature and what it contains.

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 two sentences, front-loaded with the core purpose. Every sentence adds value: the first defines what the tool documents, the second provides the usage directive. No wasted words. Excellent conciseness.

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 zero parameters, no output schema, and clear annotations (readOnlyHint), the description fully covers what an agent needs: what the tool provides (layout JSON schema, coordinate system, etc.) and when to call it. No gaps remain for this simple reference 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 has zero parameters and schema description coverage is 100% (empty object). With no parameters, the description bears no burden to document parameter meaning. Baseline score of 4 is appropriate as the description adds no parameter info but none is needed.

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 it documents the layout JSON schema, coordinate system, image handling, and workflow for Screenshot layouts. It uses a specific verb ('call this ONCE before creating or editing screenshot layouts') and distinguishes itself from sibling tools like sonar_add_screenshot or sonar_update_screenshot by being a reference guide rather than a mutation tool.

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

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

The description explicitly says 'call this ONCE before creating or editing screenshot layouts', providing clear when-to-use guidance. While it doesn't explicitly state when not to use it or name alternatives, the imperative instruction is sufficient for an agent to invoke it correctly before layout-related operations.

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 indicate write, non-idempotent, non-destructive. The description adds value by explaining the upsert behavior (idempotent effect), parameter defaults, and scope behavior. It does not describe return values, but the absence of an output schema reduces the need. 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?

Three sentences, front-loaded with the key action ('WRITE tool — create or update'). Every sentence adds essential information without redundancy. Highly efficient.

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 4 parameters, 100% schema coverage, and annotations, the description covers the main behavioral aspects (upsert key, defaults, requirements). It does not explain return values or error conditions, but this is a minor gap given the tool's nature and the lack of an 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 coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the upsert key (type+scope), how omitting threshold uses defaults, and how omitting scope_app_id makes it org-wide. This is significant added context.

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 verb ('create or update') and resource ('alert subscription in the caller's Sonar workspace'). It specifies the upsert behavior and distinguishes from sibling tools like sonar_delete_alert and sonar_list_alerts 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 gives clear context on when to use (create/update alerts) and provides guidance on parameter omission for defaults. It mentions plan and API key requirements. However, it does not explicitly contrast with alternatives like sonar_delete_alert, though sibling names are available.

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 adds significant value beyond annotations: it clarifies the write nature ('Requires a write-scope API key'), discloses the side effect of auto-enabling the locale, and explains fallback behavior. No contradiction with annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false).

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

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

Three sentences with no fluff. The first sentence states the core action and resource, the second clarifies boundaries and fallback, and the third adds side effects and prerequisites. Perfectly front-loaded and 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 tool with 3 required parameters, no output schema, and no nested objects, the description covers purpose, boundaries (geometry/styling), fallback, side effects (auto-enable locale), and prerequisites (write-scope API key). No gaps left for an agent to infer.

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 high-level context about what overrides include (text copy, localized captures/images) but does not provide additional parameter details beyond what the schema already describes. Minor added value.

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

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

The description uses a specific verb ('Write') combined with a clear resource ('locale's translation overrides for screens in a screenshot set'). It explicitly lists what is overridden (text copy, localized captures/images) and what is not (geometry/styling), effectively distinguishing this from sibling tools like sonar_update_screenshot 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?

The description provides clear context for usage, noting that geometry/styling always come from the source layout and that falls back to unspecified overrides. However, it does not directly contrast with sibling tools or state when not to use this tool, leaving some ambiguity among the many screenshot-related sibling tools.

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

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

Annotations provide idempotentHint=true, destructiveHint=false, readOnlyHint=false. The description adds: 'Idempotent: re-starring refreshes the timestamp, unstarring a non-starred keyword is a no-op.' It also discloses plan and scope requirements. 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?

Three sentences, front-loaded with purpose ('WRITE tool — stars or unstars'), then behavior, then requirements. Every sentence adds essential information. 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?

For a simple 2-parameter tool with no output schema, the description covers purpose, parameters, behavior (idempotence, timestamp), and requirements. It is self-contained and sufficient for an agent 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% with descriptions for both parameters. The description adds value by clarifying that tracked_keyword_id is the 'id' (not keyword_id) from specific endpoints. The starred parameter description is redundant but not harmful.

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?

Description explicitly states 'stars or unstars a tracked keyword'. The verb 'star/unstar' and resource 'tracked keyword' are specific and distinct. It clearly differentiates from sibling tools like sonar_track_keywords (which adds tracking) and sonar_update_keyword_note (which updates notes).

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 indicates it's a WRITE tool, notes idempotent behavior (re-starring refreshes, unstarring no-op), and lists requirements (Indie plan, write scope). However, it does not explicitly compare to alternatives or state when not to use it, but the context is sufficiently 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 provide readOnlyHint: true, and the description adds real behavioral detail: summary/movers/droppedApps always reflect the full top 200 even when limit truncates entries, movement is empty on first request, and it works without an API key with free-tier limitations. This goes well beyond what the schema or annotations alone reveal.

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

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

The description is front-loaded with a precise, actionable sentence and follows with a short use-case and essential caveats. Every sentence carries distinct value and there is no filler, repetition, or unnecessary background.

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

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

For a read-only tool with no output schema, the description compensates by naming the key result concepts (per-app rank delta, new apps, biggest movers, dropped apps) and explaining the important edge cases around first requests and the full top-200 aggregation. Together with the fully described input schema, this gives an agent enough context to select and invoke the tool correctly.

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

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

The schema already documents all five parameters with 100% coverage, so the baseline is 3. The description adds important semantic context about how `limit` interacts with the summary/movers/droppedApps aggregates and the first-request behavior, which helps an agent understand parameter consequences without overstepping 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?

'Get a store top chart' names a specific verb, resource, and scope (free/paid/grossing, overall or by category) and adds movement details that distinguish it from a generic rankings tool. It is clearly purposeful, but it does not explicitly name alternative sibling tools or state why it should be preferred over them.

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

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

The description explicitly says 'Use to see what's rising in a market or category,' which gives a concrete usage context. It also provides useful edge-case guidance (first-snapshot behavior, no API key needed), but it does not explain when not to use it or direct the agent to sibling 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 only provide readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description explicitly labels itself as a 'WRITE tool,' and adds the constraint that each product holds at most one iOS + one Android app, which is a critical behavioral constraint. Since annotations lack this detail, the description adds substantial transparency. It could arguably score 5, but there is no mention of whether the operation is reversible or what happens on conflict, leaving a minor gap.

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

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

The description is a single well-structured paragraph of three sentences, each serving a clear purpose: first sentence states the tool's action and contrast with create tool, second adds capacity constraint, third states prerequisites. 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?

Given the tool has 4 parameters (100% schema coverage), no output schema, and moderate complexity (linking store versions with constraints), the description succinctly covers the overall purpose, usage boundaries, and prerequisites. There are no missing pieces that would prevent an agent from invoking the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 4 parameters with detailed descriptions (store enum values, ISO country code format, store_id meaning, product_id NOT being a store id). The description does not add additional parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate as the description doesn't detract but also doesn't enhance parameter understanding.

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 links a second-store version to an existing Sonar product, which is a specific verb-resource combination. It explicitly differentiates this from sonar_create_product by explaining that this tool is for adding an additional store version to an existing product, not for starting a brand-new app.

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 provides explicit when-to-use guidance ('links the second-store version'), when-not-to-use guidance ('to start tracking a brand-new app, use sonar_create_product instead'), and even specifies prerequisites ('Requires an Indie plan... and an API key with the write scope'). This fully clarifies when to pick this tool over 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?

Although annotations mark destructiveHint as false, the description openly declares 'WRITE tool', warning that it modifies data. It also details the prerequisite that the product must be linked in the same store, and mentions specific plan and API key scope requirements. This goes beyond annotations, providing essential behavioral context a mutation tool without annotations might hide.

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 a single, front-loaded paragraph of two sentences. Every phrase carries weight: declaring it a 'WRITE tool', defining its action and target, establishing prerequisites, and requiring plan/scope. No filler 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?

With no output schema, a 4-parameter schema with 100% coverage, and clear sibling tool context, the description fully informs the agent. It covers purpose, when to use, prerequisites, parameter meanings, and behavioral implications of a write operation. Nothing is left ambiguous.

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. The description goes beyond by clarifying that product_id is a Sonar UUID (not a store id) and that store_id is for the competitor app only. It doesn't elaborate on the optional country parameter beyond what the schema states, but all required parameters are well-contextualized.

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 adds a competitor app under a Sonar product for keyword and ranking tracking. It uses a specific verb ('adds'), identifies the resource ('competitor app'), and distinguishes it from sibling tools like 'sonar_remove_competitor' and 'sonar_scan_competitor'.

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

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

The description explicitly tells when to use this tool: the product must already have its own app linked in the same store. It also specifies prerequisites (Indie plan, write scope API key), giving clear context that alternatives like 'sonar_create_product' or 'sonar_track_app' do not. This helps the agent decide to call this tool only after the product is set up.

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 claims idempotent behavior ('re-posting the same terms reports them as already_tracked'), but the annotations set idempotentHint=false, which is a direct contradiction. Per guidelines, score 1 when description contradicts 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 three sentences, front-loaded with a behavioral marker ('WRITE tool'), and covers purpose, idempotency, return values, and requirements without waste. 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?

Given the tool has 3 parameters, no output schema, and limited annotations, the description covers purpose, behavior, idempotency, return outcomes, and prerequisites. It is largely complete, though it could mention error handling or rate limits.

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 detailed descriptions for all three parameters. The description adds context about idempotency and outcome reporting but does not add new semantic meaning to the parameters beyond what the schema already provides. 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 clearly states the tool starts daily rank tracking for keywords on an app in the caller's Sonar workspace, using specific verbs and resource. It distinguishes from sibling tools like sonar_track_app and sonar_untrack_keywords by focusing on keyword-level tracking initiation.

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 provides clear context for when to use the tool (to start tracking keywords) and mentions requirements (Indie plan, write scope), but does not explicitly compare to alternatives or state when not to use it.

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

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

The description explicitly labels itself as a 'WRITE tool', which aligns with the annotations (readOnlyHint: false, destructiveHint: true). It states it will untrack an app and its associated tracking data, making the destructive nature clear. The idempotentHint: true annotation is consistent with the implied behavior (untracking is likely idempotent). No contradictions.

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 two sentences, front-loading the purpose and adding prerequisites in the second. Every sentence adds value. 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 tool has one simple parameter, no output schema, and the description plus annotations fully cover its behavior. The only missing element is clarifying what 'associated tracking data' means (e.g., keywords, alerts?). However, given the low complexity, this is a minor gap.

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

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

There is only one parameter, app_id, and the schema already provides 100% coverage with a detailed description (Sonar app UUID, not a store id, referencing sonar_list_apps or sonar_create_product). The tool description adds no new meaning about the parameter beyond what the schema provides. 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 clearly states the tool untracks an app and its associated tracking data in the caller's Sonar workspace. It uses a specific verb (untrack) and specifies the resource (app and associated tracking data). It distinguishes from sibling tools like sonar_track_app (opposite) and sonar_delete_product (different domain).

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 is explicit about prerequisites: it requires an Indie plan (trial counts) and an API key with the write scope. This helps the agent know when the tool can be used. However, it does not explicitly mention when not to use it or suggest alternative tools (e.g., if the user wants to just stop tracking but not delete data).

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 convey destructiveHint=true and idempotentHint=true. The description adds plan requirements and the 'WRITE' label, which is consistent. No contradiction, but it does not add significant behavioral context 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?

Two sentences, no wasted words. The key usage modes and constraints are front-loaded. Every sentence adds 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?

The description covers the operation, modes, and requirements. It does not mention the return value or confirmation, but given the lack of output schema, this is a minor gap. Still fairly complete for a simple bulk action.

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 all parameters described. The description repeats the mutual exclusivity rule already in the schema. It adds plan/scope information but not new parameter-level semantics beyond the schema.

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

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

The description clearly states it is a WRITE tool for bulk-untracking keywords for an app, specifying the two modes (all or ids). However, it does not explicitly differentiate from the sibling tool 'sonar_delete_tracked_keyword' which handles single keyword removal, but the 'bulk' aspect is implied.

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 provides clear usage constraints: requires an Indie plan, write-scope API key, and exactly one of 'all' or 'ids'. It does not explicitly state when to use this tool over alternatives like sonar_delete_tracked_keyword, but the context is sufficient for typical use cases.

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 adds significant value beyond annotations: it confirms this is a WRITE (mutating) operation (annotations are readOnlyHint=false, so no contradiction), explicitly calls out idempotency (matching idempotentHint=true), explains what 'clearing' means (null or empty string), and discloses plan/auth requirements that annotations don't cover. No annotation contradictions found.

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, no fluff. The first sentence nails purpose and scope; the second covers idempotency and plan requirements. Every word 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 simple 2-parameter tool with no output schema, the description perfectly covers the operation, idempotency, auth/plan requirements, and parameter nuances. No gaps given the context signals (high schema coverage, no nested objects, no enums).

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% (both parameters documented in schema), so baseline is 3. The description adds value by clarifying that note supports null/empty string for clearing, and that tracked_keyword_id must be the internal `id` not `keyword_id` from other tools. This contextual advice elevates it above pure schema repetition.

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 explicitly states this is a WRITE tool that 'sets or clears the note on a tracked keyword', using specific verbs (sets, clears) and identifying the resource (tracked keyword, note). It distinguishes itself from siblings like sonar_track_keywords (which adds keywords) and sonar_star_keyword (which stars keywords) by focusing exclusively on the note field.

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 clearly states when to use this tool (to set or clear a note with motivation/hypothesis), provides context about idempotency (re-sending same note is no-op), and specifies prerequisites (Indie plan, trial counts, write-scope API key). It doesn't explicitly say when NOT to use it, but the narrow scope and condition clarity make this a minor gap.

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 provide readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds value by stating 'requires a write-scope API key' (auth requirement) and 'change shows up immediately in the Screenshot Studio' (real-time effect). 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?

Four short sentences, each serving a distinct purpose: purpose, operation pattern, immediate effect, auth requirement. No wasted words; the key information is front-loaded. The structure is clean and efficient.

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 should cover return value, but it doesn't. It omits what the agent can expect after the request (e.g., updated layout object, success message). Also lacks error conditions or prerequisites beyond auth key. This gap reduces completeness for a write operation.

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%, setting a baseline of 3. The description for the 'layout' parameter adds significant meaning: 'FULL replacement — it replaces the whole document, it does not merge' and a warning about placeholders. This goes beyond schema properties and aids correct invocation.

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 it replaces one screen's layout in a screenshot set, using specific verbs and resource. It distinguishes from sibling tools like sonar_add_screenshot (adds a new screen) and sonar_delete_screenshot (removes a screen) by focusing on modification of existing content.

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 context (replace vs. add) but does not explicitly state when to use this tool over siblings. It mentions the whole-document replace pattern and warns against placeholder images, but lacks direct 'when-not' guidance or alternative tool names.

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 provide readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds that it returns the updated set with image data stripped and that removing locales loses stored translations, which is a destructive side effect not covered by annotations. It also notes the required write-scope API key, which is not in annotations. This adds meaningful behavioral context beyond annotations, earning 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?

The description is a single sentence that efficiently lists the three update operations and the return value/requirement. It is front-loaded with the main purpose and adds necessary caveats with minimal words. Each phrase adds value: operations, return format, and auth requirement. There is no redundancy or 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?

The description covers the main operations, return value, and auth requirement, which is solid for a moderately complex tool with 4 parameters and no output schema. It does not explicitly state that not all fields can be omitted (e.g., if you only want to rename, you don't need to provide locales or screen_order), but the schema indicates that only set_id is required. It also does not explain that screen_order must be a full permutation, but the schema description says that. Overall, the description is sufficient for the tool's complexity, earning a 4.

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 already has a description in the schema. The description in the tool adds context for the 'locales' parameter by mentioning that removal loses translations, and for screen_order by implying a permutation. However, it doesn't explicitly explain the 'name' parameter beyond the schema's 'New display name.' Since the schema covers the basics, the description's added value is marginal, but it does reinforce critical behaviors. 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 clearly states that the tool updates a screenshot set by renaming, replacing locales, or reordering screens, and mentions the return value. It distinguishes it from siblings like sonar_update_screenshot (which updates a single screenshot) and sonar_create_screenshot_set (which creates new sets). The verb 'update' plus the specific resource and the three operations make the purpose specific and unambiguous.

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

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

The description implies usage by listing the operations and the requirement for a write-scope API key, suggesting it's for modifications. However, it does not explicitly state when to use this tool versus alternatives like sonar_create_screenshot_set or sonar_set_screenshot_translations, nor does it provide exclusion criteria (e.g., if only adding locales, this tool might replace the list entirely). The lack of explicit when/when-not guidance keeps it at a 3.

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