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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Annotations already establish readOnlyHint=true, but the description adds substantial context: pure arithmetic over the passed text, no store lookup, answers instantly, and the semantic meaning of each warnings[].level and warnings[].rule. It also discloses the asymmetry between Google (errors) and Apple (warnings) and that valid=false only on errors. It stops short of stating rate limits or pagination, but for a stateless pure-function tool that is minor.

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?

It is a long, dense block, but it is front-loaded with the core purpose and most sentences earn their place by documenting return semantics that have no output schema. The emoji parenthetical and the keyword-field enumeration are slightly over-elaborated for the selection decision.

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

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

With no output schema, the description carries the full burden of explaining the return shape, and it does so thoroughly: per-field length/limit/remaining, warnings[].level with all three values, warnings[].rule with its enumerated policies, notes[], and the keywords object fields. An agent knows exactly what it gets back and how to act on it.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by clarifying the kw_field/store interaction ('sending a keywords field to Google Play, which has none') and distinguishing subtitle semantics across stores. Marginal but genuine 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 opens with a specific verb+resource ('Check draft listing text against the stores' own rules') and immediately scopes it against the sibling that follows ('before spending a run measuring it'). An agent can distinguish it from simulate_metadata without opening either schema.

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

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

It gives explicit usage guidance: 'run it on every draft you write, in a loop if that helps, and call simulate_metadata only once it comes back valid.' The alternative and the condition that selects it are both stated.

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, so the agent knows this is a safe read. The description adds valuable context by specifying exactly what data is returned (usage vs. allowed for multiple metrics, plus API request count for the billing period), which compensates for the absence of 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?

The description is a single, front-loaded sentence that lists all relevant metrics. While the list is long, every item earns its place by clarifying the tool's scope, and there is no redundant 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?

Given the simplicity of the tool (read-only, no parameters) and the lack of an output schema, the description provides sufficient detail about what usage metrics are included. It could mention the return format or structure, but the information is adequate for an agent to decide when and how to call it.

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

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

The tool has zero parameters and schema coverage is 100% (vacuously). The baseline for 0 params is 4; the description appropriately does not need to describe 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?

The description states a specific verb ('Get') and resource ('current account usage and plan limits'), then enumerates the exact metrics covered. No sibling tool performs this function, so it is easily distinguishable.

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 (checking account usage and plan limits) but offers no explicit when-to-use guidance, prerequisites, or alternatives. Since no sibling provides similar functionality, routing is not an issue, but the definition could be more instructive.

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 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.

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.

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.

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.

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.

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.

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

Annotations only declare readOnlyHint=true; the description adds substantial behavioral context the annotation cannot: the audit is auto-maintained and read from a stored snapshot, report is null when never audited (explicitly 'not a score of zero'), fields[].text is truncated with a truncated flag, and verdicts shift meaning with tier. This is exactly the extra context annotations leave uncovered.

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

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

Dense and front-loaded: the core purpose and attribution rationale come first, followed by output-field semantics and then the sibling routing. It is long, but with no output schema nearly every sentence carries return-value semantics that would otherwise be unavailable, so little is wasted.

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

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

With no output schema and only a readOnly annotation, the description must carry the full return-value burden, and it does: it enumerates axes, tier behavior, field states, truncation, verdict enum, ungraded/unsearched counters, assessable=false, and the null-report case. An agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds guidance beyond the schema by explaining include_words is off by default and 'detail you rarely need to answer how a listing is doing,' which helps an agent decide whether to set it.

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

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

States a specific verb and resource ('Get the full ASO Health audit of one tracked app') and immediately scopes it against the ranking concern ('how well its listing is WRITTEN, as opposed to how it currently ranks'). Names the exact field contents it returns, so an agent can distinguish it from list_applications and get_app_score_history without opening anything.

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

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

Explicitly routes the agent: 'For visibility over time instead, use get_app_score_history; to score a listing that does not exist yet, use simulate_metadata.' It also states the call is cheap and safe to repeat ('reads a stored result and answers in milliseconds: call it as often as you need'), removing hesitation about frequency.

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

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

While 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.

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.

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.

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.

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.

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.

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

Annotations declare readOnlyHint=true, and the description agrees ('Read-only and instant'), adding a latency/behavioral note the annotation does not carry. It also describes the shape of the returned data, which is valuable given there is no output schema. It stops short of anything about pagination or error behavior, but for a single-record read that is minor.

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

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

Front-loaded with the action and the returned contents, then the id sourcing, then the read-only note. The middle sentence ('This is what list_metadata_simulations cannot carry...') is slightly rhetorical but earns its place by justifying the tool's existence against a sibling.

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-param read tool with no output schema, the description compensates by enumerating the returned fields (scored fields, assumed context, score, findings). An agent has everything needed to decide to call it and to interpret the result.

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

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

With one parameter at 100% schema description coverage, the schema already documents the id and its two possible origins. The description repeats 'the id of a row from list_metadata_simulations, or the saved.id a simulate_metadata call returned' without adding format or validation detail beyond the schema, so this is baseline-3 territory.

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

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

States a specific verb and resource ('Read one saved listing draft in full') and enumerates exactly what the payload contains: the four scored fields, assumed context, achieved score, and findings. It explicitly contrasts itself with list_metadata_simulations and simulate_metadata, so an agent can distinguish it from siblings without opening a schema.

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

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

Gives explicit routing: use this when you need the text that list_metadata_simulations cannot carry, and names both valid sources of the id (a row from list_metadata_simulations or simulate_metadata's saved.id). Both the when and the required input origin are stated rather than inferred.

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

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

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.

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.

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.

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.

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.

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.

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

Annotations cover safety (readOnlyHint=true) and the description confirms 'Read-only'. Beyond that it discloses what the response contains, explains aso_health semantics including the null-on-unaudited-apps edge case, and points to get_aso_health for the breakdown — substantial context the annotations do not provide.

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

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

Front-loaded with purpose, then return contents, then workflow guidance. The long enumeration of returned fields earns its place because there is no output schema, though the single dense paragraph is heavier than ideal.

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

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

With no output schema, the description carries the full burden of describing returns and does so field-by-field, including the aso_health null case and where to get the breakdown. Nothing an agent needs to invoke or interpret this tool is missing.

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

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

Schema description coverage is 100% and the single app_id filter is fully documented in the schema, so the baseline is 3. The description mentions internal numeric IDs but adds no filter syntax or format detail beyond the schema.

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

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

States a specific verb and resource with scope: 'List all tracked mobile applications', and immediately distinguishes itself from add_application (which takes a bundle ID) and other app-scoped tools that take the numeric internal ID. An agent can identify it without opening the schema.

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

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

Explicitly says it is 'usually the first call of a workflow' and names the downstream tools (track_keywords, add_competitor, get_app_score_history) that consume the numeric ID it returns, plus the contrast with add_application. Names alternatives and the condition that selects them.

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, 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.

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.

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.

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.

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.

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.

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

Annotations cover the safety profile (readOnlyHint=true), so the bar is lower, and the description adds substantial value: it enumerates what each pair contains and explains the app_score vs competitor_score 0-100 comparison. It omits pagination and empty-result behavior, but the payload semantics are well disclosed.

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

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

Two sentences, front-loaded with the core action, then the payload detail, then the sibling pointer. The field enumeration is dense but every element is informative; slightly long, yet without an output schema it earns its length.

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

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

With no output schema, the description correctly compensates by describing the returned pair structure and score semantics, and it routes to list_applications for the omitted own-app fields. Missing only meta-behavior like pagination or result limits.

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

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

Schema coverage is 100% and the single app_id parameter is fully documented in the schema as a filter. The description never mentions filtering, so it adds nothing beyond the structured field, which is the expected baseline at 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?

States a specific verb ('List') and resource ('competitor tracking pairs') and immediately distinguishes the entity from neighboring tools add_competitor/remove_competitor. It also spells out the pair structure, so an agent knows exactly what the resource is.

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

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

It gives explicit routing for a related need — 'Use list_applications to get the full metadata of your own app' — clarifying that this tool returns only the trimmed own-app fields. It does not state when-not to use it versus add_competitor/remove_competitor, but the 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?

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.

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.

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.

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.

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.

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.

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

Annotations only declare readOnlyHint, so the description carries most of the behavioral burden and does it well: it explains that current_rank comes from the latest daily snapshot, that null rank means 'not ranked' rather than 'unknown', that ahead/behind are null in that case, and that the tool errors rather than returning partial rank data. This is far beyond what readOnlyHint provides.

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

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

Purpose is front-loaded in the first clause and the rest is a structured enumeration of returned fields. It is long, but with no output schema the field list earns its place; a minor tightening of the return-field run-on would help.

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

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

There is no output schema, so spelling out the returned fields and the null/error semantics is necessary and done thoroughly, and the pagination behavior is noted. The only gap is guidance on when to choose this over sibling keyword tools.

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

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

Schema description coverage is 100% for all four parameters, so the baseline is 3. The description adds no parameter-level detail beyond the word 'Paginated', adding essentially nothing to page, per_page, app_id, or favorites.

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

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

States a specific verb and resource ('List tracked keywords') plus the domain ('ASO metrics'), which separates it from track_keywords, untrack_keyword, and inspect_keyword. It does not explicitly name which sibling to prefer, so it falls just short of the top band.

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

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

Usage is implied by the description (it returns tracked keywords with their metrics), but there is no explicit when-to-use or when-not-to-use statement and no routing to alternatives like inspect_keyword or get_keyword_rank_history. The 'Paginated' note hints at retrieval context but is not guidance.

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

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

Annotations only declare readOnlyHint=true, so the description rightly carries the behavioral load: it discloses sort order (newest first), result provenance (runs from here or the dashboard simulator), the exact per-row fields available, the re-run count, and explicitly which fields are NOT returned. That omission list is unusually useful. It stops short of describing pagination behavior or result-size limits.

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

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

Front-loaded with purpose, then scope, then the field inventory, then the routing instruction — a sound structure with no filler sentences. The middle sentence is long because it enumerates return fields, but each clause conveys information an agent needs to interpret rows.

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

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

There is no output schema, so the description must describe the return shape itself, and it does so field by field, including what is absent and how to retrieve it. Combined with named parameters living in the schema, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100% for all three parameters (page, search, per_page), so the schema already documents them. The description adds nothing about them — it only references the sibling tool's 'id' field, not its own params. Baseline 3 applies when the schema does all the work.

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

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

States a specific verb and resource ('List the listing drafts already scored on this account, newest first') and immediately bounds scope, including that rows come from both this tool and the dashboard Metadata Simulator. It is unmistakably distinct from the sibling get_metadata_simulation, which it names.

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

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

Gives an explicit use condition ('Use this to find a past score without re-running it') and names the alternative plus the condition that selects it ('pass a row's "id" to get_metadata_simulation to read a draft in full'). Routing between the two tools is fully specified.

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

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

Annotations already declare readOnlyHint=true, but the description adds useful behavioral context: it re-reads prior work and returns summary rows only, not the clusters and keywords themselves. It does not cover auth or rate limits, but the safety profile and response scope are clear.

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

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

Three tight sentences, front-loaded with what the tool returns and followed by pagination and usage guidance. Every sentence earns its place.

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

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

With no output schema, the description still communicates the return shape: summary rows with named fields, explicitly excluding clusters and keywords. It also covers pagination and the precondition for use, so an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so page and per_page are already documented in the schema. The description confirms pagination but adds no syntax, defaults, 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.

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

States a specific verb and resource ('List the niche analyses previously run') and enumerates the summary fields returned. It also distinguishes itself from run_niche_analysis by framing itself as the prior-check tool.

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

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

Explicitly says to call it before run_niche_analysis to check whether a topic was already covered. This gives both the when and the alternative, leaving no inference required.

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

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

The readOnlyHint annotation is present, and the description 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Annotations declare openWorldHint=true and readOnlyHint=false, and the description adds real behavioral context the annotations cannot: expected latency ('a few seconds per call'), cache-warming via words_fetched, the deliberate blank-default context that floors the appeal axis, and the warning not to present a draft's global score as comparable. It flags partial-failure reporting through notes[].

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

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

Front-loaded with the core purpose and the two modes, and every sentence carries information (return shape, caveats, latency, alternatives). It is dense and somewhat long for a single description, but not padded with filler.

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

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

There is no output schema, yet the description enumerates the return payload in detail (app, aso_health axes and tier, delta with per-axis nulls, flags, saved run, notes, words_probed/words_fetched). Combined with the mode and caveat coverage, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so the schema already documents every parameter, including the app_id/required-only-without-app_id rules and the context sub-fields. The description reinforces the override/merge semantics of context but adds little that isn't already in the schema's own descriptions, so the baseline 3 applies.

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

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

States a specific verb and resource ('score a listing that does not exist yet') and immediately anchors it to a concrete outcome (gain/loss vs the app's current score). It also distinguishes itself from siblings by positioning the engine as the same one that 'audits the real ones'.

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 branches on whether app_id is present, telling the agent exactly what each mode means and which question it answers ('is my draft better than my listing'). It names alternatives with conditions: check_metadata first, get_metadata_simulation to re-read, list_metadata_simulations to list.

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.