Server Quality Checklist

Tool Scores

• list_keywordsA
  4/5.0
  Behavior3/5

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

  Annotations declare readOnlyHint=true, so the description doesn't need to restate safety. It adds useful context about pagination and the exact fields returned, which goes beyond the schema. However, it doesn't disclose details like default sort order or whether the response includes total count, which would be helpful but not critical given the read-only annotation.

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

  Conciseness5/5

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

  The description is a single, well-structured paragraph that front-loads the purpose and then lists the return fields concisely. Every sentence adds value, and it ends with 'Paginated' to signal behavior. No wasted words.

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

  Completeness4/5

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

  Given the tool's moderate complexity (4 optional params, no output schema), the description is complete enough: it explains the return fields, pagination, and filtering options. It doesn't explain default sort order or total count, but those are minor gaps for a read-only list tool with good schema coverage.

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

  Parameters3/5

  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 four parameters. The description adds no additional parameter semantics beyond what the schema provides, but it does mention pagination and the 'is_favorite' flag, which aligns with the 'favorites' filter. Baseline 3 is appropriate since the schema does the heavy lifting.

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

  Purpose5/5

  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 with ASO metrics, using a specific verb ('List') and resource ('tracked keywords'). It distinguishes itself from siblings like list_keyword_inspections and get_keyword_rank_history by focusing on the keyword list with metrics, not history or inspections.

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

  Usage Guidelines4/5

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

  The description implies usage for retrieving a paginated list of tracked keywords with metrics, and the schema provides filter parameters (app_id, favorites). It does not explicitly state when not to use it or name alternatives, but the context is clear enough for an agent to select it over siblings like get_keyword_rank_history or inspect_keyword.

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

• list_autocomplete_historyA
  4.1/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, and the description adds context about the query scope (previously run) and the returned attributes. It does not mention pagination behavior or any other side effects, but for a read-only list operation that is acceptable. The description adds some value beyond annotations but not rich behavioral detail.

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

  Conciseness5/5

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

  The description is a single sentence that is front-loaded with the action ('List') and the resource, and it enumerates the output fields without any redundant or unnecessary wording.

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

  Completeness5/5

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

  Given the low complexity of this paginated list tool, the description is complete: it specifies the resource scope, the returned fields, and combines with the schema for pagination details and the annotation for read-only safety. No output schema exists, but the description compensates by listing the return fields.

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

  Parameters3/5

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

  Schema descriptions for page and per_page are complete (100% coverage), including defaults and maximums. The tool description does not add any additional meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the verb 'List' and the resource 'autocomplete queries you have previously run', and enumerates the specific fields returned (prefix, store, country, lang, suggestion count, last query date). This effectively distinguishes it from sibling tools like list_keywords or run_autocomplete.

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

  Usage Guidelines4/5

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

  The phrase 'you have previously run' gives clear context that this is for historical review, implying use when checking past autocomplete queries. However, it does not explicitly mention when not to use it or contrast with alternatives like run_autocomplete, so it falls just short of full guidance.

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

• add_applicationA
  4.2/5.0
  Behavior4/5

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

  Annotations indicate readOnlyHint=false (write operation), openWorldHint=true (external side effects), idempotentHint=false, destructiveHint=false. The description aligns and adds detail: it fetches metadata, computes visibility score, links to workspace, and triggers plan cap usage. This goes beyond the annotations by explaining what side effects occur, 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.

  Conciseness5/5

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

  The description is two sentences, front-loaded with the core action and then key side effects. Every sentence adds value: the first explains the process, the second highlights a critical business constraint (plan cap). There is no fluff or redundancy.

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

  Completeness4/5

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

  The tool has 4 required parameters and no output schema. The description explains the internal steps (fetch, compute, link) and the plan cap implication, giving a good sense of what happens. It does not mention return value or failure cases (e.g., duplicate app), but given the simplicity and available annotations, this is adequate. A 4 is justified for providing a clear behavioral model.

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

  Parameters3/5

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

  Schema description coverage is 100% for all four parameters, so the schema already documents each parameter well. The description mentions 'store bundle ID' which maps to app_id, but does not add additional semantic meaning beyond what the schema provides. Baseline of 3 is appropriate given high coverage.

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

  Purpose5/5

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

  The description clearly states the action: 'Track a new mobile application by its store bundle ID'. It specifies the resource (mobile application), the verb (track), and the mechanism (store bundle ID). It distinguishes from siblings like add_competitor or track_keywords by focusing on app tracking and the subsequent steps (metadata fetch, score computation, workspace link).

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

  Usage Guidelines4/5

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

  The description communicates when to use this tool (to track a new app) and provides critical context: 'Counts against the plan app cap' implies a constraint. It does not explicitly name alternatives, but the sibling tools indicate other add operations (add_competitor), and the description's specificity makes the use case clear.

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

• inspect_keywordA
  4.2/5.0
  Behavior4/5

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

  The description discloses quota implications (inspecting tracked keywords does not consume quota) and provides a detailed list of return values. It does not contradict the annotations (readOnlyHint false is fine; the tool may have side effects like quota usage, but that is disclosed). It adds value beyond annotations by explaining the quota nuance, which is important for agents.

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

  Conciseness4/5

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

  The description is concise but thorough, covering the tool's purpose, the data returned, and a specific behavioral note (quota). It is front-loaded with the main action and then details. It could be slightly more concise but is well-structured and informative.

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

  Completeness5/5

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

  The description is comprehensive for a tool with no output schema. It enumerates all major return elements (difficulty, traffic, KEI, top 20 apps with specific attributes, suggestions, tracking status) and mentions the quota policy. This is sufficient for an agent to understand what the tool does and what to expect from it.

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

  Parameters3/5

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

  The input schema has 100% coverage, with all four parameters clearly described. The description does not add significant new meaning beyond what the schema already provides; it only reiterates that 'keyword' is the target. Since schema coverage is complete, baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: 'Deep-analyze any keyword' and lists exactly what it returns (difficulty_score, traffic_score, KEI, top apps, related suggestions, tracking status). It distinguishes from sibling tools like track_keywords and list_keywords by specifying it analyzes keywords even if untracked, and focuses on deep analysis rather than tracking or listing.

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

  Usage Guidelines4/5

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

  The description implies when to use: when you need deep analysis of any keyword, even untracked ones. It also mentions the quota behavior, indicating that inspecting tracked keywords is free. However, it does not explicitly mention alternatives or exclusion criteria, but the context is clear enough for an agent to know it's different from tracking or listing tools.

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

• list_keyword_inspectionsA
  4.2/5.0
  Behavior4/5

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

  Annotations declare readOnlyHint=true, and the description adds valuable behavioral context beyond that: it lists the returned fields (last inspection date, current difficulty/traffic scores) and discloses the quota-saving behavior. No contradiction with annotations.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the primary purpose and followed by a concrete use case. Every word earns its place with no redundancy or filler.

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

  Completeness4/5

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

  The description covers the main return content and the key behavioral benefit, making the tool understandable even without an output schema. It could mention pagination or ordering, but those are already covered by the input schema and are not critical for this simple list operation.

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

  Parameters3/5

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

  Schema coverage is 100%, and the parameter descriptions for page and per_page are already self-explanatory. The tool description does not add further parameter-level meaning, so baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the action ('List') and the resource ('keywords you have previously inspected'), and distinguishes this from sibling tools like list_keywords and inspect_keyword by emphasizing the historical inspection context and quota-free benefit.

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

  Usage Guidelines4/5

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

  The description gives clear context on when to use the tool ('revisit past keyword research') and the advantage of not consuming inspection quota, but it does not explicitly name alternative tools or state when not to use it.

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

• run_autocompleteA
  4.2/5.0
  Behavior4/5

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

  Annotations indicate readOnlyHint=false, idempotentHint=false, and destructiveHint=false, which is ambiguous; the description compensates by stating that each call consumes one autocomplete query and one API request, a valuable quota/cost disclosure. However, it does not describe response format or failure behavior, and lacks any note on whether the operation is read-only.

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

  Conciseness5/5

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

  Two sentences, every sentence earns its place: the first defines the operation and stores, the second adds practical use and quota cost. No filler or repetition.

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

  Completeness4/5

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

  For a simple 4-parameter lookup with full schema coverage and a clear cost warning, the description is mostly complete. It does not describe return values or how to interpret autocomplete results, but no output schema exists, which is a minor gap. Overall adequate for a straightforward tool.

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

  Parameters3/5

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

  Schema description coverage is 100%, with each parameter (store, country, lang, prefix) already documented in the input schema. The description adds no extra semantic detail beyond the schema except prefix length, which is already in the schema. Baseline 3 applies because the schema does the heavy lifting.

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

  Purpose5/5

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

  The description clearly states the tool fetches autocomplete suggestions from App Store or Google Play for a given prefix, with a specific character range. It names both stores, matching the GPLAY/ITUNES enum, and the 'discover what users are searching for' framing adds practical purpose. This distinguishes it from sibling tools like inspect_keyword or top_charts.

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

  Usage Guidelines4/5

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

  The description indicates this is useful for discovering user search terms starting with a seed, and notes it consumes one autocomplete query and one API request. Sibling names show alternatives like get_keyword_rank_history or top_charts, but the description does not explicitly state when not to use it compared to those tools. Still, the usage 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.

• run_niche_analysisA
  4.2/5.0
  Behavior4/5

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

  Given the annotations (readOnlyHint=false), the description adds meaningful behavioral context: it notes that cache hits avoid quota consumption and fresh analyses take minutes. It implies result persistence but does not fully clarify whether repeated calls create or update records. This goes beyond the bare annotation, providing useful operational details.

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

  Conciseness5/5

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

  The description is concise but information-dense, using a clear colon-separated structure to enumerate actions, outputs, and caching behavior. No redundant phrasing; each sentence contributes to the overall understanding.

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

  Completeness4/5

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

  Since there is no output schema, the description compensates by outlining the return content (clusters, keywords, scores, intent, app suggestion). It also covers caching and quota implications. It does not address error cases or rate limits, but provides sufficient context for typical usage.

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

  Parameters3/5

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

  All parameters (topic, store, country, lang) are fully described in the input schema with examples. The tool description does not add additional semantic nuance beyond what the schema already provides, so it meets the baseline without enhancement.

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

  Purpose5/5

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

  The description explicitly states the tool 'runs a niche analysis' and details its core functions (discovering keywords, clustering, scoring). It clearly differentiates from sibling tools like list_niche_analyses or top_charts by focusing on the analysis execution rather than listing pre-existing data.

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

  Usage Guidelines4/5

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

  The description provides practical usage context by mentioning caching behavior and quota consumption, which helps the agent decide when to invoke it (e.g., for fresh analysis vs. cached results). It does not explicitly name alternative tools, but the distinction is inferable from sibling names, and the caching details are valuable guidance.

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

• top_chartsA
  4.2/5.0
  Behavior3/5

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

  The annotation readOnlyHint=true already covers the read-only nature. The description adds value by specifying the daily rank movement and delta vs. yesterday, which implies historical comparison, but it does not disclose any other behavioral aspects like pagination, rate limits, or data freshness beyond the snapshot date. Since annotations are present, a score of 3 is appropriate as the description provides some extra context but not exhaustive.

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

  Conciseness5/5

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

  The description is a single, well-structured paragraph that front-loads the core purpose, then explains parameters in a logical sequence. It uses commas and semicolons to separate ideas, making it readable without being verbose. Every sentence adds value, and there is no filler.

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

  Completeness4/5

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

  Given the tool has 5 parameters, 100% schema coverage, and no output schema, the description compensates by listing the output fields (snapshot date, ranked apps with details) and explaining default behaviors for category and collection. It does not describe the output schema in detail, but since there is no output schema, the description provides enough context for an agent to understand what to expect. However, it might benefit from mentioning the response structure more formally, hence 4.

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

  Parameters3/5

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

  Schema coverage is 100%, and the description reiterates the parameter meanings (store, country, category, collection, limit) with clarifications like 'category' accepts OVERALL or genre IDs, and collection defaults. The description adds examples for category values, but the schema already describes these, so the marginal value is slight, justifying a baseline 3.

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

  Purpose5/5

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

  The description clearly states the tool gets a store top-chart ranking for a country, category, and collection, with daily rank movement. It specifies the return fields and distinguishes itself from sibling tools by detailing what it returns (rank, app_id, etc.) and how to specify categories and collections, which is more specific than sibling tools like list_top_chart_categories.

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

  Usage Guidelines5/5

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

  The description provides explicit usage guidance: how to choose between App Store and Google Play, category values (including default OVERALL and examples), and collection options (free, paid, grossing). It does not explicitly state when not to use this tool versus alternatives, but it clearly explains the input parameters, which is enough for selection among siblings like list_top_chart_categories.

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

• list_competitorsA
  4.3/5.0
  Behavior4/5

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

  The readOnlyHint annotation already establishes this is a safe read operation, and the description adds concrete behavioral expectations by enumerating the returned metadata and the 0-100 app_score vs competitor_score comparison. It does not contradict the annotation and provides more transparency than the bare annotation alone.

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

  Conciseness5/5

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

  The description is compact but information-dense, front-loaded with the core action and then unpacking the return value in a structured way. No filler or redundant restatement of the tool name appears.

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

  Completeness5/5

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

  Even without an output schema, the description fully tells an agent what to expect: each pair includes metadata for both apps and both key visibility scores. It also clarifies the semantic purpose (direct ASO comparison), making the tool self-explanatory for selection and invocation.

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

  Parameters3/5

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

  The input schema has full parameter description coverage with 'Filter competitors by application internal ID', so the description does not need to add much. It does not elaborate further on the filtering behavior or how the optional app_id affects the list, but the schema already conveys the meaning.

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

  Purpose5/5

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

  The description opens with a specific verb+resource construct: 'List competitor tracking pairs.' It clearly distinguishes the tool from siblings like add_competitor and remove_competitor by focusing on listing existing pairs, and it further clarifies the output includes app metadata and visibility scores for ASO comparison.

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

  Usage Guidelines4/5

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

  The description gives clear context for when to use this tool: to see tracked competitor pairs and directly compare visibility scores. It does not explicitly state exclusions or alternatives, but the sibling names make the contrast visible and the phrase 'for direct ASO comparison' signals the intended use case.

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

• add_competitorA
  4.4/5.0
  Behavior5/5

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

  Annotations already provide readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds valuable context by specifying that metadata is fetched from the store and ranking entries are backfilled for each tracked keyword. This goes beyond the annotations and clearly communicates the external side effects and data creation, which is exactly what the dimension rewards.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the primary action, and contains no fluff. It efficiently conveys the tool's purpose and the key process details without unnecessary elaboration.

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

  Completeness4/5

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

  For a moderate-complexity tool with full schema coverage and relevant annotations, the description sufficiently explains the operation. It does not mention error handling or response format, but with no output schema and the clarity provided, the description is adequate. Minor gaps like prerequisites (e.g., having an application with tracked keywords) are implied but not explicit, preventing a perfect score.

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

  Parameters3/5

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

  Schema description coverage is 100%, meaning all parameters are described in the input schema. The tool description does not add substantial meaning beyond what the schema already provides. It repeats that the competitor is identified by bundle ID, but that is already in the schema. Therefore, the description adds minimal value, placing it at the baseline for high schema coverage.

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

  Purpose5/5

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

  The description clearly states the tool adds a competitor app to an existing application, specifies the identifier (store bundle ID), and outlines the side effects (fetch metadata, backfill rankings). It distinguishes itself from siblings like add_application (which adds main apps) and list/remove_competitor (which manage competitor lists).

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

  Usage Guidelines4/5

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

  The description implicitly conveys when to use it: when you want to track a competitor's rankings for an app. However, it does not explicitly mention alternatives or exclusions (e.g., what if the competitor already exists). The context from sibling tools (list_competitors, remove_competitor) makes the purpose clear, but there is no explicit '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.

• get_account_usageA
  4.4/5.0
  Behavior4/5

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

  Annotations already indicate readOnlyHint: true, and the description reinforces this with 'Get'. More importantly, it adds behavioral context by specifying the exact categories of usage (e.g., keyword inspections, autocomplete queries) and that it reflects 'used vs. allowed' for the 'current billing period'. No contradictions; the description enriches beyond the annotation.

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

  Conciseness5/5

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

  The description is a single, well-structured sentence that front-loads the core purpose ('Get current account usage and plan limits') and efficiently lists the covered categories with a colon and commas. No verbosity, perfect length for the complexity.

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

  Completeness4/5

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

  Given the absence of parameters and output schema, the description provides a solid overview of the expected return data (usage counts for six categories plus API requests, with 'used vs. allowed' limits). It does not explicitly state the response format, but for a zero-param read-only endpoint, the coverage is thorough enough for an agent to understand what to expect.

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

  Parameters4/5

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

  The tool accepts zero parameters, so the description is not required to elaborate on any parameter semantics. Per the rubric, a baseline of 4 applies to zero-parameter tools. The description does not need to compensate for schema gaps because there are no parameters.

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

  Purpose5/5

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

  The description uses a specific verb ('Get') and clearly identifies the resource ('current account usage and plan limits'), then enumerates the exact data categories (applications, keywords, competitors, etc.) and temporal scope ('current billing period'). This makes the tool's purpose immediately clear and distinguishes it from sibling list_* tools.

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

  Usage Guidelines4/5

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

  The description clearly implies 'use this when you need usage/limit info' and indirectly differentiates from siblings like list_applications (which return actual records), but it does not explicitly mention alternatives or state when not to use it. The context is clear; explicit exclusions are missing.

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

• remove_competitorA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's job is light. The description adds useful context about the relation row ID vs. the competitor app ID, which is a common pitfall. It doesn't contradict annotations. It could mention irreversibility, but this is adequately covered.

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

  Conciseness5/5

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

  One sentence, no fluff, and it front-loads the critical clarification about the ID type. Every word earns its place.

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

  Completeness4/5

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

  For a simple single-parameter destructive tool, the description is complete. It's clear what the ID refers to, where to get it, and what happens when invoked. The only minor gap could be explicit mention of the irreversibility, which the destructiveHint annotation already covers. No output schema exists, so no need to describe return values.

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

  Parameters4/5

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

  Schema coverage is 100%, and the description reinforces the critical meaning of the relation_id parameter, clarifying potential confusion with the competitor app ID. The parameter name and schema description are sufficient, and the description adds the crucial distinction between the relation ID and app ID.

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

  Purpose5/5

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

  The description clearly states the tool removes a competitor relationship using a specific internal relation ID, explicitly distinguishing this from the competitor app ID. It's a specific verb-resource pair that differentiates from siblings like add_competitor and list_competitors.

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

  Usage Guidelines4/5

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

  The description implicitly tells when to use the tool (when you have the relation ID from list_competitors or add_competitor) and clarifies the ID is not the app ID. It doesn't explicitly mention alternatives, but the sibling context makes the usage clear.

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

• track_keywordsA
  4.4/5.0
  Behavior5/5

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

  The description adds significant behavioral detail beyond the annotations: 'Each keyword triggers an immediate ranking fetch' (external side effect), 'Already-tracked keywords return a per-keyword error in results' (duplicate handling), and 'previously removed keywords are reactivated automatically' (complex stateful behavior). These go far beyond the basic readOnlyHint/openWorldHint/idempotentHint flags.

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

  Conciseness5/5

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

  Three sentences, each carrying essential information: purpose, side effect, and error/reactivation behavior. No redundant or filler content. Front-loaded with the core action.

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

  Completeness4/5

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

  Given 5 required parameters and no output schema, the description covers the essential behavioral context: what triggers, how duplicates are handled, reactivation, and input source. It doesn't describe the success response format, but that's not critical in absence of an output schema. Minor gap: no mention of rate limits or cost implications of the 'immediate ranking fetch,' but overall complete.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3. The description does not add new parameter semantics; it repeats the app_id source (already in schema) and mentions 'up to 20' (matching maxItems). No additional clarity on parameter formats or constraints beyond what the schema provides.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Track up to 20 new keywords for one of your applications in a single call.' It uses a specific verb (track) and resource (keywords), and distinguishes itself from siblings like untrack_keyword and list_keywords by focusing on creation/reactivation.

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

  Usage Guidelines4/5

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

  Provides clear context: 'Use app_id from list_applications results' gives a concrete source for a required parameter. It also implies when to use this tool (to add or reactivate keywords) through behavioral notes, but does not explicitly contrast with alternatives like untrack_keyword or state when not to use it.

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

• list_applicationsA
  4.5/5.0
  Behavior4/5

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

  The annotation provides readOnlyHint=true, but the description adds 'Read-only, consumes no quota,' which goes beyond the structured annotation. It also details the fields in the returned metadata, which is useful for an agent without an output schema. It stops short of mentioning pagination or filter behavior, but overall it adds meaningful context.

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

  Conciseness5/5

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

  Every sentence earns its place: opening purpose, a compact list of returned fields, workflow positioning, parameter clarification relative to siblings, and the read/no-quota note. It's detailed but appropriately sized for a foundational tool.

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

  Completeness5/5

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

  Given it has no output schema, the description hands over the full return field list. It also identifies related sibling tools and explains exactly why calling this tool first matters, making it complete for the intended role.

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

  Parameters3/5

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

  Schema coverage is 100% because the only param app_id has a clear description in the schema. The tool description does not add extra parameter context beyond the schema, but that is not required when the schema already explains the filter.

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

  Purpose5/5

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

  The description begins with 'List all tracked mobile applications,' a specific verb plus resource and scope. It also distinguishes itself from siblings by explaining that it returns numeric internal IDs for app-scoped tools, whereas add_application takes a store bundle ID.

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

  Usage Guidelines5/5

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

  Explicitly states it is 'the first call of a workflow' and tells agents which sibling tools expect the internal ID vs which expect a bundle ID. This provides clear when-to-use and alternative-when-not guidance.

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

• set_keyword_favoriteA
  4.5/5.0
  Behavior4/5

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

  Annotations already indicate this is a write operation that is idempotent and non-destructive. The description adds valuable behavioral context about per-app independent favorite states and the need for tracked rows, which is not captured by the annotations. No contradictions exist.

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

  Conciseness5/5

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

  Two sentences, no filler, and the primary action is front-loaded. The second sentence adds a meaningful scoping detail about independent favorite states. Every sentence earns its place.

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

  Completeness5/5

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

  For a straightforward three-parameter setter with full schema descriptions and useful annotations, the description is complete. It explains parameter provenance, per-row behavior, and the action, and no output schema exists to require return-value documentation.

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

  Parameters4/5

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

  Schema coverage is 100%, so baseline is 3, but the description adds provenance by stating both keyword_id and app_id come from list_keywords results. It also clarifies the boolean's toggling behavior with 'true to mark as favorite, false to unmark' in the schema, though the source-of-truth note provides extra value beyond the schema.

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

  Purpose5/5

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

  The description opens with a specific verb phrase, 'Mark or unmark a tracked keyword as favorite for a specific app,' clearly defining the tool's action and scope. It also differentiates from siblings like track_keywords and untrack_keyword by focusing on the favorite state rather than tracking status.

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

  Usage Guidelines4/5

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

  The description gives clear usage context by specifying that favorites are stored per tracking row and that keyword_id and app_id come from list_keywords results. It does not explicitly name alternative tools or state when not to use it, but the guidance is sufficient for a simple setter.

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

• untrack_keywordA
  4.5/5.0
  Behavior5/5

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

  Behavioral transparency is strong. It goes beyond annotations by explaining the soft-delete semantics, that historical data is preserved, that re-adding reactivates the row, and that the operation is idempotent. These details align with and enrich the destructive and idempotent hints.

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

  Conciseness5/5

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

  Three concise sentences deliver purpose, important behavioral nuance, and idempotency without extra words. Each sentence contributes meaningful information.

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

  Completeness5/5

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

  For a mutation tool with no output schema, the description is complete: it covers the action, result semantics, side effects, reversibility, and idempotent failure behavior. No critical gaps remain for an agent to use it correctly.

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

  Parameters3/5

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

  The schema already covers 100% of parameters with descriptions stating both are internal IDs sourced from list_keywords results. The description adds no new parameter-level details, so the baseline score of 3 applies.

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

  Purpose5/5

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

  The description clearly states a specific action ('Stop tracking a keyword') targeting a specific resource ('for the specified app'), and clarifies it is a soft delete. It distinguishes itself from the sibling tool track_keywords by clearly defining the inverse operation.

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

  Usage Guidelines4/5

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

  The description implies the appropriate context: use it to remove keyword tracking while preserving historical data, and re-add later using a tracking tool. However, it does not explicitly name track_keywords or mention when not to use it, though the sibling relationship is clear from context.

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

• list_niche_analysesA
  4.7/5.0
  Behavior5/5

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

  The description adds context beyond the readOnlyHint annotation by stating it consumes no niche-analysis quota and returns only summary rows (not clusters/keywords). This matches the annotation without contradiction, and enriches the safety profile.

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

  Conciseness5/5

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

  Two concise, front-loaded sentences that cover purpose, usage, safety, and return format without fluff. Every phrase earns its place.

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

  Completeness5/5

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

  For a simple list operation with two optional parameters and no output schema, the description fully covers what it returns, its read-only nature, quota-free status, and pagination. It leaves no critical gaps.

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

  Parameters3/5

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

  Schema coverage is 100%, so both parameters (page, per_page) are already documented. The description only reiterates that pagination is via page and per_page, adding marginal meaning. Per rubric, baseline 3 is appropriate since the schema already handles parameter semantics.

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

  Purpose5/5

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

  The description clearly states the tool lists previously run niche analyses, specifying the fields returned (topic, store, country, etc.), which is a specific verb+resource. It distinguishes from sibling tools like run_niche_analysis by explicitly contrasting listing vs. running.

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

  Usage Guidelines5/5

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

  It provides explicit guidance on when to use this tool: 'call it before run_niche_analysis to check whether a topic was already covered.' It also notes it's read-only and free, which helps the agent decide between this and quota-consuming alternatives.

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

• get_keyword_rank_historyA
  4.9/5.0
  Behavior5/5

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

  While readOnlyHint=true already signals a safe read, the description goes beyond by detailing default date range, clamping of future dates, swapping of reversed dates, and the PLAN_LIMIT error condition. It also discloses the nested return structure (apps[] with history[]), which is not present in the annotations or schema. This is excellent supplementary transparency.

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

  Conciseness4/5

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

  The description is information-dense but well-structured: opening purpose, return format, defaults, constraints, error handling, parameter guidance, and an explicit alternative tool. Every sentence contributes value, though it could be tightened slightly by merging some related clauses. At ~120 words, it remains scannable and front-loaded.

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

  Completeness5/5

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

  For a tool with no output schemacherschema, the description fully covers what to expect in the response (fields like keyword, store, country, lang, resolved dates, apps[] structure). It also covers error handling (PLAN_LIMIT), parameter relationship, and edge cases. Given that the schema already defines the inputs, this is near-comprehensive for a read-only API call.

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

  Parameters5/5

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

  With 100% schema coverage, the baseline is 3, but the description adds significant meaning: it explains that keyword_id comes from list_keywords, app_id narrows output, and the from/to parameters have default behavior and clamping rules. This goes well beyond the schema descriptions, which only state 'Defaults to 30 days ago' etc., by also defining how invalid inputs are handled.

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

  Purpose5/5

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

  The description opens with a clear verb-phrase 'Get the daily rank history of one tracked keyword' and immediately distinguishes it from the sibling get_app_score_history by noting the alternative for app-level visibility. The scope ('one tracked keyword', 'one series per app') is precise and differentiates this from other list/inspection tools.

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

  Usage Guidelines5/5

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

  Explicitly states when to use it (daily rank history for a keyword), how to obtain required identifiers ('Pass keyword_id from list_keywords'), and when not to (use get_app_score_history for whole-app visibility). Also documents limits (400-day cap, plan depth) and edge-case handling, giving the agent clear context for invocation.

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

• get_app_score_historyA
  5/5.0
  Behavior5/5

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

  Beyond the readOnlyHint annotation, the description details behavior around date resolution: reversed dates are swapped, future dates are clamped to today, and score is null on days without a snapshot. It also discloses the plan history depth cap and PLAN_LIMIT error, giving the agent strong expectations of tool behavior.

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

  Conciseness5/5

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

  The description is front-loaded with the core capability, followed by tightly packed but relevant behavioral details. Every sentence contributes useful information, and there is no redundant filler or restating of obvious schema content.

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

  Completeness5/5

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

  Even though there is no output schema, the description clearly enumerates the return shape (app_id, app_title, resolved dates, history[] with date and score). It covers default behavior, error conditions, date edge cases, and ID requirements, making the tool fully comprehensible for an agent.

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

  Parameters5/5

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

  Although the schema already covers all parameters with descriptions, the tool description adds critical semantics beyond the schema: app_id must be the numeric internal ID from list_applications, not the store bundle ID, and date windows are auto-corrected/capped. This significantly improves invocation correctness.

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

  Purpose5/5

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

  The description clearly states the tool 'Get the daily visibility score history of one application' with a specific verb and resource. It defines the visibility score concept and explicitly distinguishes itself from the sibling get_keyword_rank_history by noting that tool is for one keyword rank over time.

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

  Usage Guidelines5/5

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

  The description provides concrete when-to-use guidance: for app-level visibility history over time, defaulting to last 30 days, with explicit alternative get_keyword_rank_history for keyword-level rank data. It also specifies important constraints like the 400-day cap, PLAN_LIMIT errors, and ID source requirements.

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

• list_top_chart_categoriesA
  5/5.0
  Behavior5/5

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

  The readOnlyHint annotation is present, and the description adds context about the output's usage in top_charts. No contradictions or missing information about side effects.

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

  Conciseness5/5

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

  The description is concise, two sentences, and well-structured, providing essential information without unnecessary detail.

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

  Completeness5/5

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

  Given the schema, annotations, and description, the tool is fully specified. It explains what it lists, how to filter, and how to apply the results, making it complete for its purpose.

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

  Parameters5/5

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

  The schema fully describes the 'store' parameter with an enum and a clear description ('Filter to one store; omit to get both'), and the tool description reinforces its role. Parameter semantics are well-covered.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: listing categories and collections supported by the top_charts tool, per store. It distinguishes itself from sibling tools by its specific role as a helper for top_charts.

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

  Usage Guidelines5/5

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

  The description explicitly instructs how to use the output (category keys and collections) as inputs to top_charts, making the usage context clear even without explicit when-not statements.

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