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

With no annotations provided, the description bears full burden. It discloses the need for a write-scope API key and implies that append is at the end. However, it does not detail behaviors such as idempotency, error conditions, or limits on screens per set, leaving some behavioral ambiguity.

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: a single sentence conveying the core action, a hint about reordering, and a key requirement. Every word adds value, and it is 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 the large sibling set and no output schema, the description covers the essential aspects: what the tool does, how it relates to a specific sibling, and what credentials are needed. It lacks details on edge cases or error handling, but for a simple append operation 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% with good descriptions for both parameters. The tool description adds no new parameter details beyond what the schema already provides, so it does not significantly enhance understanding. 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 action (append a screen to a screenshot set) and distinguishes from the sibling tool sonar_update_screenshot_set by noting that this tool appends at the end and reordering is done with the sibling.

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

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

The description explicitly mentions when to use this tool (append) and directs to an alternative for reordering. It also notes the requirement for a write-scope API key, which guides proper usage. However, it does not discuss scenarios where this tool is not appropriate or compare with other related tools like sonar_create_screenshot_set.

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?

No annotations provided, so description carries full burden. It describes the tool as a read-only calculation returning data; does not mention any side effects or permissions, but the non-destructive nature is implied.

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

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

Two sentences, front-loaded with key action and output, no unnecessary information. Efficient and clear.

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 parameter set and no output schema, the description fully explains what the tool does and returns. Adequate 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 description coverage is 100%—all parameters well-described. The tool description adds context about the output but not additional parameter details, meeting the baseline for high 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?

Clearly states it calculates an ASO audit score (0-100) for an app and returns overall score plus breakdown of specific checks. Distinguishes from sibling tools that focus on individual metrics like keywords or reviews.

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

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

Implied usage is for holistic ASO audit, but no explicit when-to-use or alternatives. Since sibling tools cover specific aspects, some guidance would help, but the purpose is clear enough.

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=true; description adds 'newest first' ordering and plan requirement. 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?

Two sentences, no extraneous information; efficient and 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?

No output schema, but description enumerates change types and sorting. Adequate for a history tool without needing return-value details.

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 covers all parameters (100%), but description adds value by clarifying app_id as Sonar UUID and noting it's not a store ID, exceeding 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?

Description clearly states verb (view/history) and resource (app changes), and distinguishes from sibling tools like sonar_app_rankings by specifying the types of changes.

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

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

Provides a specific use case (correlating rank movements) and mentions plan requirement. Lacks explicit when-not-to-use or alternatives, but 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?

No annotations are provided, so the description must carry the burden of disclosing behavioral traits. It describes the action as extracting keywords (a read operation) but does not discuss permissions, rate limits, output structure, or any side effects. It is adequate but not thorough.

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, efficient, and front-loaded with the action. Every word earns its place; no redundancy or 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 no output schema, the description should compensate by describing the return format. It only mentions 'ranked by relevance', which is vague. For a simple extraction tool, this is adequate but incomplete without specifying the structure of the output.

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?

Input schema has 100% description coverage, so baseline is 3. The tool description adds no additional meaning beyond the schema's own parameter descriptions; it does not clarify or expand on any parameter semantics.

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

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

The description clearly states the tool extracts target keywords from an app's title and description, ranked by relevance. It specifies the action ('Extract') and resource ('keywords from an app'), but does not explicitly differentiate from sibling tools like sonar_competitor_keywords or sonar_app_keywords, which could overlap.

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 the use case ('understanding what an app is optimizing for'), which implies when to use it, but does not specify when not to use it or mention alternative tools among the many keyword-related siblings.

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

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

Annotations declare readOnlyHint=true, and the description aligns by describing a read operation. It adds context on pagination (cursor, default 50 per page) and return value references, which go beyond the annotation. 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 (three sentences) with information front-loaded. Each sentence adds distinct value: listing fields, linking to other tools, pagination, and plan requirement. 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?

No output schema exists, so the description must explain return values. It does so by listing fields and referencing IDs. Pagination behavior is noted. Minor gap: exact response structure (e.g., next_cursor) is implicit but not explicit.

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 parameter descriptions. The description adds minimal value beyond the schema, e.g., default page size. Baseline of 3 is appropriate as the schema already documents parameters well.

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 tracked keywords for an app, specifying exact fields returned. It distinguishes itself from sibling tools by mentioning the returned IDs used by sonar_update_keyword_note, sonar_star_keyword, and sonar_keyword_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 indicates when to use the tool (to list tracked keywords) and implicitly separates it from mutation tools. It also notes a prerequisite (Full plan). However, it does not explicitly state 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?

No annotations are provided, so the description must fully disclose behaviors. It only lists returned fields but does not mention read-only nature, error handling, rate limits, or data freshness, leaving critical 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?

Two succinct sentences with no waste: first states action, second lists outputs. Efficient and well-structured.

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 lookup tool with 3 well-documented parameters and no output schema, the description covers return fields fairly well. However, it omits error behavior and response format details, which would improve 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?

Schema coverage is 100% with detailed parameter descriptions. The description adds output context but does not enhance parameter semantics beyond what the schema already provides, meeting 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 verb 'look up' and the resource 'app by its store ID', listing returned metadata. However, it does not differentiate from sibling tool 'sonar_get_app' which likely overlaps in purpose.

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 no context on when to use this tool vs alternatives, no exclusions or prerequisites. It simply states what it does without usage guidance.

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

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

Annotations already declare readOnlyHint=true; description adds pagination behavior (cursor, default 50) and plan restrictions (Full plan required). 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?

Three sentences: purpose, use cases, pagination+plan. Front-loaded with core definition. 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?

Covers purpose, usage, pagination, plan, and references related tools. Lacks explicit return format details but output schema is absent; still sufficient for a data retrieval tool.

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

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

Schema coverage is 100% so baseline is 3. Description adds minimal value beyond schema, e.g., referencing sonar_app_keywords for keyword_id. Pagination note is about behavior not parameters.

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

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

Clearly states it provides rank history for an app's tracked keywords with daily ranks per keyword. Distinguishes from sibling tools like sonar_keyword_rankings (keyword-level) and sonar_app_keywords (list 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?

Explicit use cases: check rankings after metadata change or find trending keywords. Mentions cursor pagination and plan requirement. Does not explicitly exclude alternatives but implies app-level focus.

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?

No annotations are provided, so the description must fully disclose behavior. It mentions returning a confidence grade and methodology, which adds transparency. However, it does not disclose potential limitations, data freshness, or whether the estimate is model-based. Gaps exist but 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 a single sentence plus a directive, efficiently conveying the core action and output. It is front-loaded with the main purpose. Minor redundancy ('always communicate') could be integrated, but overall 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 no output schema, the description adequately explains return values (dollar estimate, confidence grade, factors, methodology). However, it lacks details on edge cases (e.g., apps with no data) or confidence interpretation. For a simple 3-param tool, it is mostly complete.

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

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

Schema coverage is 100%, with all three parameters already described in the input schema. The description adds no new meaning to the parameters; it only references external data sources (installs, ratings, benchmarks) not captured as parameters. Baseline 3 applies.

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

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

The description clearly states the verb 'estimate', the resource 'monthly revenue', and the basis (install counts, ratings, category benchmarks). It distinguishes itself from siblings like sonar_app_aso_score or sonar_app_keywords by focusing on revenue estimation and returns.

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 to 'always communicate the confidence alongside the number', which is a usage guideline. However, it does not explicitly state when to use this tool versus alternatives (e.g., when to use sonar_app_revenue vs sonar_app_aso_score). No when-not or alternative guidance is provided.

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 no annotations, the description must disclose behavioral traits. It fails to mention that the tool is read-only, whether authentication is needed, rate limits, or pagination behavior. The description only restates the schema's capabilities without additional behavioral 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?

Two concise sentences: first states purpose, second lists features and use cases. No 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?

No output schema exists, so the description should clarify return structure. It only says 'Fetch user reviews' without describing fields like text, rating, date, or metadata. Adequate for a simple tool but lacks completeness for an agent to set expectations.

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 only high-level mentions of filtering and sorting, which are already detailed in the schema. No additional semantic value beyond what the 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 fetches user reviews for an app, with filtering and sorting capabilities. It distinguishes from siblings like sonar_app_keywords or sonar_app_revenue by focusing on reviews, and the use cases further clarify its purpose.

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

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

The description lists use cases (sentiment analysis, feature-request mining, competitive research) and mentions supported filters and sort orders. It does not explicitly state when not to use the tool, but the sibling set contains no other review tool, so ambiguity is minimal.

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 no annotations, the description carries full burden. It transparently states the tool returns a ranked list with metadata in store ranking order, which is sufficient for understanding the output. However, it does not disclose potential issues like rate limits or pagination behavior (though the 'num' parameter handles count).

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

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

Two sentences with zero wasted words. Key information (search behavior, stores, output format) is front-loaded and clearly conveyed.

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 adequately explains the return value (ranked list with metadata). For a search tool with well-defined parameters, this is sufficient. Minor missing details (e.g., error handling) are not critical.

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 parameters. The description adds no additional parameter-specific meaning; it only explains the output format. Baseline 3 is appropriate as the description does not enhance parameter understanding 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?

Description clearly states 'Search apps in the App Store or Google Play by keyword' with a specific verb and resource. It distinguishes itself from sibling tools like sonar_app_lookup (specific app lookup) and sonar_keyword_search (keyword metrics) by focusing on app search by 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?

Description provides minimal guidance beyond the basic use case. It does not explicitly state when to use this tool versus alternatives (e.g., sonar_app_lookup for known apps, sonar_keyword_suggestions for brainstorming). Usage context is implied but not fully articulated.

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 the readOnlyHint annotation by disclosing that data is from the last 7 days of SERP data and that a Full plan is required. 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 concise with two sentences covering purpose, gap analysis, pagination, and requirements. Every sentence contributes meaningful information without 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 no output schema, the description adequately explains the returned data (keywords with difficulty/popularity, gap marker) and pagination behavior (cursor-based, default 50). It lacks details on response structure but is sufficient for a retrieval tool with well-documented parameters.

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 description adds meaning beyond the schema by clarifying that competitor_app_id is a Sonar UUID (not store id) and explaining the effect of own_app_id (marks gap keywords). The schema already has 100% coverage, so baseline is 3, but the extra context justifies 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 clearly states the tool retrieves keywords a tracked competitor ranks for, including difficulty and popularity, and distinguishes from sibling tools like sonar_app_keywords (own app keywords) by focusing on competitor data and gap analysis.

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

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

The description provides context on when to use the tool (to get competitor keywords) and explains the optional own_app_id for gap analysis. However, it does not explicitly state when not to use it or mention alternatives like sonar_app_keywords for own keywords.

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

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

Annotations (readOnlyHint=false, destructiveHint=false) are consistent with description's 'WRITE tool — creates a product'. Description adds behavioral context: requires Full plan, write scope, and returns IDs for downstream use. No contradictory statements. It could mention idempotency or duplicate behavior, but overall 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 three sentences, each serving a clear purpose: tool type and action, product definition, and output + requirements. Front-loaded with 'WRITE tool' for immediate clarity. No unnecessary 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 no output schema, the description successfully explains what is returned and how it connects to other tools. It covers auth and plan requirements. Minor gap: could mention error handling for duplicates or plan insufficiency, but overall complete for a creation 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% with detailed descriptions for each parameter. The description adds value by explaining the product concept and linking parameters to output (product id, Sonar app ids), which helps understand the role of the optional name parameter and the apps array constraints.

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 that creates a product and starts tracking apps. It defines the product concept and distinguishes itself from siblings by specifying the returned IDs needed by other tools (sonar_track_keywords, sonar_track_competitor). The verb and resource are specific and unique among 40+ 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?

The description explains when to use (to create a product and start tracking), and prerequisites (Full plan, write-scope API key). It does not explicitly state when not to use or provide alternative tools, but the context is clear enough.

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?

Describes immediate visibility and editability in Screenshot Studio, and the need for write-scope API key. With no annotations, this provides useful behavioral context beyond the basic create action.

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 concise sentences, front-loaded with the core purpose. No superfluous text; 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?

Covers prerequisites, authorization, and immediate behavior, but omits full response details (e.g., returned set ID or status). With no output schema, the description could be more 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?

The schema already describes all parameters with 100% coverage, including the screens/template_id mutual exclusivity. The description adds guide-reading context but no new parameter-specific detail beyond 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 action 'Create' and the resource 'app-store screenshot set', distinguishing it from sibling tools like sonar_update_screenshot_set or sonar_add_screenshot. It also specifies the context of being visible in Screenshot Studio, adding precision.

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 advises reading sonar_screenshot_layout_guide first and mentions requirement for a write-scope API key. However, no explicit alternative exclusions are given; usage context is implied by the sibling tool listing.

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 readOnlyHint=false. The description adds meaningful context: the plan requirement and scope, which are not covered by 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 two short sentences with no wasted words. The key information (verb, resource, prerequisites) 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 1-parameter destructive tool with no output schema, the description covers purpose, prerequisites, and parameter source. It could mention error behavior or success response but is largely 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%, baseline 3. The description adds value by referencing the source of the id parameter (sonar_list_alerts or sonar_set_alert), helping the agent understand where to obtain the UUID.

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'), the resource ('alert subscription'), and the scope ('in the caller's Sonar workspace'). It distinguishes from sibling tools like sonar_set_alert (create/update) and sonar_list_alerts (list).

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 ('Full plan', 'write scope API key') and labels the tool as a 'WRITE tool'. It does not explicitly state when not to use it, but the purpose is clear enough to guide 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 indicate destructive and idempotent nature. Description adds context about untracking apps and plan/scope requirements, extending beyond annotations.

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

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

Two sentences, front-loaded action, no extraneous text. Every sentence provides value: action result and prerequisites.

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

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

For a one-parameter delete tool, description covers key behavioral aspects and requirements. Missing details about return value or error cases, but low complexity mitigates need.

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 covers product_id with detailed description (100% coverage). Tool description adds no further parameter info, so 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 explicitly states 'delete a product and untrack its apps' with specific verb and resource. It distinguishes from siblings like sonar_delete_alert by naming the product 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?

Provides clear prerequisites (Full plan, write-scoped API key) but does not explicitly guide when to use over other delete tools. Context from tool name and resource difference mitigates this slightly.

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 no annotations, description discloses rejection of last screen deletion and write-scope auth requirement. Adequate for a simple delete operation, though could mention idempotency or reversibility.

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 front-loaded action. No unnecessary words. Efficient and clear.

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

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

For a single-parameter delete tool with no output schema, description covers purpose, constraint, and auth. Missing details on response or side effects, but sufficient for basic usage.

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 covers 100% with description for screenshot_id. Description adds minimal extra meaning beyond schema; essentially restates purpose of parameter.

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

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

Describes exact action: delete one screen from a screenshot set. Distinct from sibling tools like sonar_delete_screenshot_set and sonar_add_screenshot. States constraint about rejecting deletion of the last remaining screen.

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

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

Implies usage by specifying action and constraints (write-scope key required, last screen rejected) but does not explicitly compare with alternatives like sonar_delete_screenshot_set or sonar_update_screenshot.

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?

Discloses destructive behavior (permanently delete), irreversibility, write-scope requirement, and cascading deletion of child items. No annotations exist, so description carries full burden effectively.

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, front-loaded with action and irreversibility, then requirements and advice. 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?

Covers action, scope, irreversibility, and authorization. Lacks specification of return value or async behavior, but for a simple delete operation with one parameter, this 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 coverage is 100% with parameter 'set_id' described as 'Screenshot set id.' Description does not add parameter-level semantics beyond schema, so 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?

Description clearly states the tool permanently deletes a screenshot set and all its contents (screens, translations), which is specific and distinguishes it from sibling delete tools like sonar_delete_screenshot.

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

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

Provides clear guidance: requires write-scope API key and user confirmation. While it doesn't explicitly mention alternatives or when not to use, the action is well-defined and context from sibling tools fills the 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 declare readOnlyHint=false, idempotentHint=true, and destructiveHint=true. The description adds useful context beyond annotations by labeling it as a 'WRITE tool', stating the plan requirement, and confirming it deletes a tracked keyword pair. 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 extremely concise (two sentences) and front-loaded with the verb and resource. Every word serves a purpose—no fluff 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?

For a simple delete tool, the description covers purpose, parameter source, and requirements. However, it omits what the response looks like (e.g., success confirmation), which could be useful given no output schema. Still, the missing information is minor given the tool's simplicity.

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

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

Schema description coverage is 100% for the single parameter, and the schema already explains that tracked_keyword_id is a UUID from sonar_app_keywords, not the keyword_id. The main description essentially restates this, adding no new semantic 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 explicitly states the action (stop tracking), the resource (one keyword/app pair), and how to identify it (tracked-keyword id from sonar_app_keywords). This clearly distinguishes it from sibling tools like sonar_untrack_keywords which operate on batch or other resource types.

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 specifies when to use the tool (for stopping tracking a single pair) and provides prerequisites (Full plan, write-scoped API key). However, it does not explicitly exclude cases where batch deletion (sonar_untrack_keywords) would be more appropriate, leaving room for confusion.

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, and the description adds context by specifying the data returned (store metadata and up to 90 daily snapshots) and the plan requirement. This goes beyond the annotation to inform the user about data limits 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 two sentences, front-loaded with the main action and quickly adds a requirement. Every sentence is necessary with no redundancy.

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

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

Given the tool's complexity (detailed reports with snapshots) and no output schema, the description adequately explains the output content and plan requirement. Minor gaps like error handling are acceptable for a read-only 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 input schema has one parameter 'app_id' with a comprehensive description explaining its origin and uniqueness (NOT a store id). Schema coverage is 100%, so the description adds no additional value beyond the schema, resulting in a baseline score of 3.

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

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

The description uses a specific verb 'Get' and resource 'full details for one tracked app', clearly indicating the action and scope. It distinguishes from siblings like sonar_list_apps by specifying 'one tracked app' and details the data included (metadata + 90 daily snapshots).

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 retrieving details of a single app but does not explicitly state when not to use it or contrast with alternative sibling tools. It does mention the requirement of a 'Full plan', which provides a prerequisite but no exclusion criteria.

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

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

Discloses default placeholder substitution for inline images and explains the include_image_data flag's effect and rationale (readability, update constraints). No annotations provided, so description carries full burden.

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

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

Two sentences, front-loaded purpose, no wasted words. Essential information conveyed efficiently.

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, but description adequately describes response contents (layout JSON, translation overrides) and key behavioral note about placeholders. Parameters fully documented.

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 parameter descriptions already explaining behavior. Description ties parameters to overall behavior but does not add significant new semantics beyond 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?

Description clearly states 'Fetch a screenshot set in full' with specific details about contents (layout JSON, translation overrides), distinguishing it from list, create, update, delete 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?

Implied usage as a fetch operation for full details, but no explicit when-to-use or alternatives given. Could mention sibling sonar_list_screenshot_sets for listing without details.

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?

No annotations exist, so description fully bears transparency. It discloses credit cost per keyword, bulk limit (25), and that it returns metrics. It does not describe the return structure, but the core behavioral traits are covered 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?

Extremely concise: two sentences with zero wasted words. Front-loaded with main purpose and immediately useful 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?

Given no output schema, the description covers usage, parameter constraints, cost, and sibling differentiation. It lacks explicit mention of return format, but the metric names ('Difficulty + popularity') imply the output. For a simple query tool, 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?

Schema descriptions cover all parameters (100% coverage). The description adds extra clarity by explaining the mutual exclusivity of 'keyword' and 'keywords' parameters, and ties credit cost to the 'keywords' list. This adds value 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?

Description clearly states the tool fetches difficulty and popularity metrics for keywords, with up to 25 in bulk. It distinguishes from sibling 'sonar_keyword_search' by specifying the exact use case.

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

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

Explicitly says when to use this tool ('when you already know which keywords you care about') and when to use the alternative ('sonar_keyword_search instead when you want related keyword ideas alongside metrics'). Also mentions credit cost.

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

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

Annotations indicate readOnlyHint=true, so the tool is read-only. The description adds that results are 'newest first' and include 'which apps ranked in the top results on each measured day.' This clarifies sorting and scope. 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?

Three sentences: first defines the tool, second provides the use case, third adds requirements. Every sentence adds essential information without redundancy. Highly concise and 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 the tool is simple (2 params, no output schema), the description covers purpose, usage, constraints, and parameter meaning. It does not mention pagination or result format, but 'top results' and 'newest first' give enough context. Annotations are sparse, so description carries the burden adequately.

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 keyword_id is a UUID from specific sources (sonar_app_keywords or sonar_competitor_keywords) and that it is 'NOT the keyword text.' For days, it restates the default 30, which is already in schema but reinforces the constraint.

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

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

The description clearly states the tool provides 'SERP history for one tracked keyword' with apps ranked on each measured day. It distinguishes itself from siblings like sonar_app_rankings (which covers multiple keywords for an app) and sonar_competitor_keywords (listing tracked keywords). The verb is implied and the resource is specific.

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: 'to see who competes on a keyword and how the top spots shifted over time.' Also includes prerequisites: 'keyword must be tracked in the caller's Sonar workspace' and plan requirement: 'Requires a Full plan (trial counts).' This provides complete usage 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?

Without annotations, the description carries full burden. It discloses that the tool returns difficulty (0-100), popularity score, results count, and autocomplete suggestions. It does not mention any destructive actions or side effects, but as a research tool, this is appropriate. The behavioral description is good but could note if there are any rate limits or authentication requirements.

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

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

The description is two sentences: first explains the action and outputs, second states the use case. It is front-loaded and contains no unnecessary words. 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's complexity (3 parameters, no output schema, no annotations), the description covers the core purpose and outputs adequately. It could elaborate on how difficulty/popularity are calculated or provide examples, but for a keyword research tool, it is sufficiently complete for an agent to understand its function.

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 the context of 'related autocomplete suggestions' but does not enhance parameter meanings beyond what the schema already provides (e.g., seed keyword, store, country). The value added is marginal.

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 researches a keyword and related terms, and specifies the exact outputs: difficulty, popularity score, results count, and autocomplete suggestions. It explicitly tells the agent to use it for finding keywords worth targeting, distinguishing it from sibling tools that focus on specific app or keyword operations.

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 says 'Use this to find keywords worth targeting,' which provides a clear usage context. However, it does not mention when not to use this tool or suggest alternatives among the many sibling tools like sonar_keyword_metrics or sonar_competitor_keywords. The guidance is implicit rather than explicit.

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

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

No annotations provided, but description covers main behavior: returns suggestions with priority scores. States it's lighter/faster. Lacks details on error handling, limits, but adequate for a simple autocomplete 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?

Two sentences: first states purpose, second gives usage guidance. No fluff, front-loaded. 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?

No output schema, but mentions return includes priority score. Input well-documented. Context of sibling tools and simple nature make this complete enough for agent selection and 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 covers 100% with descriptions. Description adds minimal context beyond schema (e.g., seed keyword starts suggestions). Baseline at 3 is appropriate as no significant extra meaning.

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?

Clear verb 'get' and specific resource 'autocomplete suggestions for a seed keyword' from two stores. Distinguishes from sibling sonar_keyword_search by noting lighter/faster 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?

Explicitly compares to sonar_keyword_search and states when to use: when only need term ideas without difficulty/popularity scoring. Provides clear decision 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 provide readOnlyHint=true, confirming a safe read operation. The description adds context about requiring a Full plan (trial counts), which is useful behavioral information not covered by annotations. 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?

Two sentences, front-loaded with the primary action, precise and to the point. Every word 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?

For a parameterless list tool, the description covers the content of the list and a prerequisite (plan). It does not mention sorting or pagination, but those are minor omissions for such a simple 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?

No parameters exist, so baseline 4 applies. The description adds meaning by explaining what each alert rule contains (change type, scope, threshold, enabled), which goes beyond the empty schema.

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

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

The description clearly states the tool lists alert subscriptions, specifying that each alert rule defines change type, scope, threshold, and enabled status. It is distinct from sibling tools like sonar_set_alert and sonar_delete_alert.

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 when to use the tool (to list alert subscriptions) and includes a plan requirement (Full plan). It implicitly distinguishes from creating/deleting alerts but does not explicitly 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?

Annotations already declare readOnlyHint=true, so bar is lower. Description adds useful context: cursor-paginated with default 100 per page and plan requirement, which are behavioral traits not covered by 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 main purpose. Every sentence adds unique value: listing with snapshots, providing UUIDs, pagination details, and plan requirement. No redundancy.

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

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

No output schema, so description should explain return values. It mentions UUIDs and snapshot fields but does not list them explicitly. However, for a list tool with good annotations, this is acceptable 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% with descriptions for both parameters. Description adds value by specifying default 100 per page for limit and clarifying cursor for pagination, improving clarity beyond 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?

Clear verb ('List') and resource ('apps tracked in the caller's Sonar workspace') with specific output details (latest snapshot, UUIDs). Distinguishes itself from siblings by noting it provides UUIDs needed by several other 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?

Mentions pagination and plan requirement. Implicitly guides that other tools require UUIDs from this call, but no explicit exclusions or when-to-use vs alternatives given.

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 a key behavioral constraint: the tool requires a Full plan (trial counts). It also describes the output contents (store versions, competitor counts) without relying on an output schema.

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

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

Two sentences, front-loaded with a clear verb and resource, no unnecessary words. 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?

Given no output schema and no parameters, the description covers purpose, output content, and a usage prerequisite. It does not detail the exact structure of the returned data, but is sufficient for a simple list tool.

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

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

Since the schema has no parameters, the description adds meaning by detailing what the response includes (linked store versions, competitor counts, UUIDs). This compensates for the lack of parameters entirely.

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 products with linked store versions and competitor counts, and explicitly mentions discovering UUIDs. This distinguishes it from sibling tools like sonar_list_apps, which list apps rather than 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 specifies a primary use case ('to discover product/app UUIDs'), providing clear context for when to use this tool. However, it does not explicitly exclude alternatives or provide 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?

No annotations are provided, so the description must disclose behavior. It mentions 'metadata only', implying a read operation, and lists output fields. However, it does not fully describe rate limits, authentication needs, or potential side effects, which is acceptable for a simple list tool but not comprehensive.

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 concise sentences, front-loaded with the action and output, and 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?

Given the tool's simplicity (1 parameter, no output schema, no annotations), the description covers the essential aspects: what it lists, what it returns, and how to get more detail. Minor omissions like sorting or pagination are acceptable.

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

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

Schema description coverage is 100% and already explains the parameter. The main description adds no significant meaning beyond what the 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 verb 'list', the resource 'screenshot sets', and the scope 'metadata only'. It also distinguishes from the sibling tool 'sonar_get_screenshot_set' by noting it provides 'full layouts'.

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 usage context (listing metadata for a product) and directs to an alternative tool for more detail. However, it does not explicitly state when not to use or provide 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 indicate destructiveHint=true and readOnlyHint=false. The description adds operational context like plan requirement and API key scope, enhancing transparency beyond annotations. However, lacks details on side effects or reversibility.

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 conveys purpose, type, and requirements. No unnecessary words; every piece of information is relevant.

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 removal tool with 2 parameters and no output schema, the description covers the essential purpose and prerequisites. It would benefit from mentioning idempotency (annotated but not described) or result expectations, but overall 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 coverage is 100% with clear parameter descriptions. The tool description does not add any additional meaning or context beyond what the schema provides, so 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 explicitly states it is a WRITE tool that removes a competitor from a product, with clear resource context (caller's Sonar workspace). It distinguishes from sibling tools like sonar_track_competitor or sonar_scan_competitor by specifying the removal action.

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

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

The description provides prerequisites (Full plan, write scope API key) but does not offer guidance on when to use this tool versus alternatives, such as other competitor-related tools. Missing explicit when-to-use or when-not-to-use advice.

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?

Description explicitly warns about the tool being heavy and slow (~30s+), which is beyond annotation hints. It also clarifies that the return is counts, not the full keyword data, and that results are read via a different tool. This is valuable transparency.

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 well-structured, with key information upfront. Every sentence adds value without 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?

The description covers all essential aspects: purpose, behavior (heavy, slow), return value (counts), required follow-up (read with sonar_competitor_keywords), and prerequisites (plan, scope). No gaps given 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?

Parameter descriptions in the schema are comprehensive, explaining the source of the IDs. The tool description reinforces that the competitor must be tracked but doesn't add new semantics. Thus, the description adds limited value 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 performs a keyword discovery scan on a tracked competitor, recording ranks for both the competitor and own app. It also differentiates from the sibling sonar_competitor_keywords by noting that tool is for reading results afterwards.

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: it's a write tool that is heavier and requires write scope and Full plan. It explicitly directs to use sonar_competitor_keywords to read results. However, it doesn't name specific sibling tools to avoid or compare to.

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 indicates the tool lists data without stating it's read-only. As a list operation, this is typically safe, but without annotations, the description could be more explicit about its non-destructive nature. It does add context about return content (canvas dimensions, store).

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 clear sentences with no fluff. The first sentence states what the tool does and its output, and the second provides a usage hint. Every word is necessary and 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 list tool with no parameters and no output schema, the description fully covers what the tool returns (devices, dimensions, store) and how it fits into a workflow. No missing information.

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 no parameters (100% coverage). The description doesn't need to explain parameters; it already states what the tool returns. Baseline for 0 parameters is 4, and the description adds no redundant param info.

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 'List' and clearly identifies the resource: device sizes supported for app-store screenshot sets, with details on canvas dimensions and store association. It also distinguishes from related tools by linking to 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 explicitly states when to use this tool: 'Pick a device here before sonar_create_screenshot_set.' This provides clear context for usage, though it doesn't mention when not to use it or offer alternatives beyond the implied workflow.

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 no annotations provided, the description carries the full burden. It clearly indicates the tool is a reference with no side effects (it 'documents' and 'describes'), implying it is read-only and non-destructive. However, it could explicitly state that it has no impact on data or state.

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 consists of two sentences: the first states the purpose and recommendation, the second lists the contents. It is concise, front-loaded, and 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?

Given that the tool is a reference with no parameters or output schema, the description adequately covers its functionality and usage recommendation. It would benefit from noting whether the output is static or dynamic, but overall it is sufficiently complete for an agent to understand its role.

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 coverage is 100% (empty schema). The description focuses on what the output provides (a reference document), which is appropriate. Since there are no parameters to describe, a baseline of 4 is justified.

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

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

The description clearly identifies the tool as a 'layout-format reference' for Sonar screenshot sets, specifying its role as a guide for creating or editing layouts. It lists what it documents (JSON schema, coordinate system, etc.), distinguishing it from other screenshot action tools (e.g., sonar_add_screenshot, sonar_update_screenshot).

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

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

The description explicitly states 'Call this ONCE before creating or editing screenshot layouts', providing a clear when-to-use instruction. While it doesn't explicitly state when not to use it (e.g., if already familiar with the format), the context of a reference tool is sufficient for most agents.

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 show non-idempotent, non-read-only. Description adds upsert behavior and default logic. No contradictions. Adds value beyond annotations.

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

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

Three sentences, front-loaded with purpose, no redundant words. Highly efficient and well-structured.

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 operations, parameter behavior, plan requirement. Lacks error details or response format but sufficient for a non-output-schema 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 covers 100% of parameters. Description adds upsert key (type+scope), optional omission semantics (threshold, scope_app_id), and default behaviors, exceeding schema 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?

Clearly states 'create or update an alert subscription', specifies 'WRITE tool', and distinguishes from siblings like sonar_delete_alert and sonar_list_alerts.

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

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

Explicitly describes when to use (create/update) and provides parameter guidance (omit for defaults), plan requirement, and scope. Does not explicitly mention alternatives but context is clear.

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

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

Without annotations, the description carries full burden. It discloses the write operation, auto-enables locale, replaces overrides wholesale, and specifies fallback behavior. Could be clearer on idempotency but adequately transparent.

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 succinct, front-loaded with the core action, and every sentence adds value. No unnecessary 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 no output schema, the description covers purpose, behavior, and constraints adequately. Mentions write-scope requirement. Lacks error handling details but sufficient for selection.

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 clear descriptions for all parameters. The description adds context about auto-enabling locale but does not significantly enhance parameter meaning beyond the schema's examples.

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 the tool writes translation overrides for screens, mentions text copy and localized captures, and distinguishes it from siblings like sonar_update_screenshot_set or sonar_add_screenshot, which have different 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 provides context on when to use it: for setting translations, notes that geometry/styling come from source, and mentions the locale auto-enable and required write-scope API key. It lacks explicit alternatives or when-not-to-use statements but gives sufficient guidance.

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

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

Adds behavioral details beyond annotations: idempotency details (re-starring refreshes timestamp, unstarring non-starred is no-op), plan requirement, and write scope. Annotations already provide idempotentHint, description enriches it.

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

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

Concise single paragraph, front-loaded with 'WRITE tool', no waste. 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?

Complete for a simple tool with no output schema; covers behavior, requirements, and idempotency. Could mention success response but not critical.

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 param descriptions. Description adds value by clarifying that tracked_keyword_id comes from specific endpoints, enhancing the schema information.

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?

Clearly states it stars/unstars tracked keywords, distinguishes from sibling tools by specifying it's a write operation for favoriting, not tracking or other actions.

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 calls out as WRITE tool, mentions idempotency, plan requirement, and scope. Could be improved by contrasting with similar tools like sonar_track_keywords.

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

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

Annotations already indicate a write operation (readOnlyHint=false), but the description adds important behavioral context: each product holds at most one iOS + one Android app, and it's a WRITE tool. This goes 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 two sentences, front-loading the purpose and action. Every sentence is necessary: the first explains the operation and constraint, the second provides the alternative and requirements. 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 write tool with no output schema, the description covers purpose, constraints, requirements, and usage boundary. It does not explain return values or error handling, but given the simplicity and the presence of sibling tools for creation, 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?

The input schema has 100% coverage with clear descriptions for each parameter. The description reinforces the meaning of product_id (not a store id) and the purpose of the tool, adding value beyond the schema. Baseline is 3 due to high coverage; the extra context justifies 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 explicitly states it links a second-store version of an existing Sonar product (e.g., adding Android to an iOS app). It uses a specific verb ('links') and resource ('product'), and distinguishes from the sibling tool sonar_create_product by noting the different use case.

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 when-to-use (linking a second store version to an existing product) and when-not-to-use (for a brand-new app, use sonar_create_product). It also specifies prerequisites: requires a Full plan and an API key with write 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?

Discloses it's a WRITE tool and requirements, but does not mention behavior if competitor already tracked or other side effects. Annotations are neutral, 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?

Two sentences, front-loaded with purpose and behavior, followed by requirements. 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?

Adequately describes purpose, prerequisites, and write nature. Lacks output description, but for a simple add tool, 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?

Input schema covers all parameters (100% coverage). Description reiterates the purpose but adds no new semantic details 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?

Clearly states it adds a competitor app for tracking keywords and rankings, but does not explicitly distinguish from sibling tools like 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?

Provides prerequisites: product must have own app linked, requires Full plan and API key with write scope. Lacks explicit when-not-to-use or 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?

The description adds behavioral details beyond annotations: it explicitly states it's a write operation (despite readOnlyHint=false in annotations, which is consistent), idempotent behavior (though annotations have idempotentHint=false, creating a contradiction), and return outcomes (created/already_tracked/failed). The idempotency claim is transparent but conflicts 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 three sentences with no redundant information. It front-loads the action ('WRITE tool'), immediately states purpose, then adds key behavioral notes (idempotent, return outcomes) and requirements (plan, scope). 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?

Given no output schema, the description covers return values (per-keyword outcomes). It also specifies plan and scope requirements. Missing details like error handling, rate limits, or behavior with invalid app_ids, but for a tool with rich schema and clear action, it is largely 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?

The input schema has 100% parameter description coverage, so the description adds minimal additional meaning beyond what the schema already provides. The description mentions idempotency which relates to the keywords parameter's duplicate handling, but this is already implied by the schema's description of 'already-tracked terms are reported, not duplicated'.

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 'starts' and resource 'daily rank tracking for one or more keywords on an app', which distinguishes it from sibling tools like sonar_track_app (tracks entire app) or sonar_competitor_keywords (competitor tracking). The scope is well-defined.

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's a WRITE tool, requires a Full plan and write-scope API key, and is idempotent. However, it does not explicitly provide guidance on when to use this tool versus alternatives (e.g., sonar_track_app, sonar_delete_tracked_keyword), leaving the agent to infer based on the verb and resource.

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 context beyond annotations (e.g., plan and scope requirements). It aligns with readOnlyHint=false and destructiveHint=true, no contradictions. The idempotentHint is supported by the irreversibility of untracking.

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: first states the action and scope, second lists prerequisites. No redundant or excessive text.

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

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

Covers the essential aspects: what it does, prerequisites, and scope. No output schema needed; the action is simple and well-documented.

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 a detailed parameter description. The tool description repeats the parameter usage ('the id returned by sonar_list_apps') but adds no new semantic information.

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 'untrack an app and its associated tracking data' with a clear verb and resource, distinguishing it from sibling tools like sonar_track_app and sonar_delete_product.

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

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

Explicitly states prerequisites (Full plan, write-scoped API key) and context (caller's workspace), but does not directly address when not to use it or mention alternatives beyond what is 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?

The description labels itself as a 'WRITE tool', which aligns with annotations (readOnlyHint=false, destructiveHint=true). It adds context about requiring a Full plan and write scope, and mentions that trial counts apply. No contradictions with annotations. The idempotentHint annotation (true) is not explicitly discussed, but the description's phrasing implies idempotency through 'remove every' or 'remove specific ones'.

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, highly efficient, and front-loaded with the key action and constraints. Every sentence adds essential information: core function, parameter selection rule, and prerequisites. No fluff 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?

The tool has no output schema, but given its destructive nature and clear side effects, the description adequately covers the 'what' and 'how'. It lacks return-value details or error handling, but for a bulk-untrack operation, these are secondary. The prerequisites and parameter logic are well covered.

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% (all parameters described). The description adds value beyond the schema by clarifying the bulk-action nature and the requirement for exactly one of `all` or `ids`. It also reinforces the plan and scope requirements, though the schema already documents mutual exclusivity. The description's context about 'trial counts' is a semantic addition.

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 it is a 'bulk-untrack keywords for an app' tool, distinguishing it from sibling tools like sonar_delete_tracked_keyword, which likely handles single removals. The verb 'untrack' and resource 'keywords' are specific, and the scope is clear.

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

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

The description clearly explains when to use `all: true` versus `ids: [...]` and emphasizes mutual exclusivity ('exactly one of the two'). It also lists prerequisites (Full plan, write scope). However, it does not explicitly state when not to use this tool or mention alternatives, though the mutual exclusivity guidance is strong.

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

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

Discloses it's a WRITE tool, idempotent, requires Full plan and write-scope API key. This adds behavioral context beyond annotations (idempotentHint=true, destructiveHint=false). 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?

Two sentences, front-loaded with key information ('WRITE tool'), no redundancy. 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 no output schema, description covers all necessary context: purpose, idempotency, plan requirement, and parameter semantics. 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%, but description adds value by explicitly stating that null or empty string clears the note, clarifying the 'note' parameter's behavior beyond schema description.

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 clearly states the tool sets or clears a note on a tracked keyword with concrete examples (why tracked, hypothesis, reminder). Differentiates from all sibling tools by specifying the exact action and resource.

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 examples of when to use (optimization hypothesis, reminder) but lacks explicit when-not-to-use or alternatives. However, no sibling tool serves the same purpose, so context is 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?

Discloses that the operation is a full replace (non-merge), that changes are immediate, and that write-scope is required. No annotations are provided, so description carries the burden. It doesn't explicitly mention destructive nature, but the 'replace' and 'sends it back' imply overwriting.

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 sentence serves a purpose. The description is short, front-loaded with the main action, then provides necessary behavioral and parameter details. 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?

Though there is no output schema, the description covers all needed context: what the tool does, how to use it (fetch-modify-send), immediate effect, permission requirement, and a specific caution about layout content. It is complete for safe 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?

Adds critical guidance beyond the schema: warns against sending placeholder text and advises refetching with include_image_data. The schema description for layout is already clear about full replacement, but the additional caution is valuable.

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 ('replace') and identifies the resource ('one screen's layout in a screenshot set'). It distinguishes from siblings by emphasizing 'whole-document replace' vs. add or set-level updates.

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

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

It clearly states the tool is for replacing a full layout, not merging, and requires a write-scope API key. It implies a fetch-modify-send workflow. However, it does not explicitly mention when not to use or name alternatives like sonar_add_screenshot.

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?

No annotations provided, so description carries full burden. It discloses return format (image data stripped) and a key behavioral detail: locales removed lose stored translations. It also mentions auth requirements. Could mention if set must exist.

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

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

Two sentences, front-loaded with actions, then return and auth info. No 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?

Missing output schema, but description covers return value (updated set with image data stripped). Auth requirement stated. Slight gap: no mention of prerequisite that set exists. Overall adequate for 4 simple params.

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 has 100% coverage with parameter descriptions. The tool description adds context linking parameters to actions (rename, replace locales, reorder) and warns about locale removal consequences. Adds value beyond 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 three actions: rename, replace locale list, and reorder screens. It distinguishes itself from sibling tools like create, get, delete, and update single screenshot.

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

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

The description explains what the tool does and requires a write-scope API key, but does not explicitly say when to use it versus alternatives like sonar_set_screenshot_translations or sonar_add_screenshot. It lacks 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.