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

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: metadata is fetched from the store, an initial visibility score is computed, the app is linked to the user's workspace, and the call consumes plan quota. It stops short of covering duplicate/invalid-ID handling, which matters given idempotentHint=false.

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

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

Three short sentences, front-loaded with the action and resource, with the side effects and quota caveat following in priority order. No filler or redundant restatement of the title.

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

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

For a 4-parameter mutation with no output schema, the description discloses the side effects, the store-fetch step, the score computation, and the quota cost, which is most of what an agent needs. It omits failure modes (invalid bundle ID, already-tracked app) that would complete the picture.

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

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

Schema description coverage is 100% with enum values and format examples for lang, store, country and app_id, so the schema does the heavy lifting. The description mentions only the bundle ID and adds no format, defaulting, or interplay details beyond what the schema already documents, making the baseline 3 appropriate.

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

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

The description opens with a specific verb+resource ('Track a new mobile application') and adds the keying mechanism ('by its store bundle ID'), which cleanly separates it from list_applications, add_competitor, and track_keywords. An agent can identify the operation without opening the schema.

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

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

Usage is only implied – the agent can infer 'call this when you want to start tracking an app', but no alternative is named (e.g., when to prefer this over add_competitor) and no prerequisites or preconditions are stated. The plan-cap note is a constraint, not guidance on when 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 declare non-read-only, non-idempotent, open-world and non-destructive, and the description adds real value beyond them: metadata is fetched remotely ('from the store', reinforcing the open-world hint) and ranking entries are backfilled for every tracked keyword — a non-obvious side effect that the annotations alone do not convey.

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

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

Two sentences with zero filler. The core action and identifier come first, and the side-effect context follows, making it well 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 5-required-param mutation with no output schema, it covers the action, the identifying key, the external fetch, and the keyword backfill side effect. It stops short of stating whether the backfill is immediate or asynchronous and gives no hint of a return value, which leaves a minor gap.

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

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

With 100% schema description coverage across all five parameters, the schema already documents app_id, store, country, lang and competitor_app_id. The description only restates that the competitor is identified by store bundle ID, adding no new syntax or format detail, so baseline 3 applies.

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

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

Specific verb ('Add') plus resource ('a competitor app to one of your applications') with the identification key (store bundle ID) named up front. It is clearly distinct from the sibling add_application and remove_competitor, so an agent can select 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?

It implies usage context by describing the backfill over 'every keyword tracked on the main app', which tells the agent this is tied to an existing tracked app. However, it never says when to prefer this over list_competitors/remove_competitor or what prerequisites (e.g., the app must already exist) apply.

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/openWorldHint/destructiveHint, but the description goes far beyond: it discloses the non-obvious store asymmetry (Google names forbidden words and rejects; Apple leaves it to a reviewer), that `valid` is false only on an ERROR, that a valid draft can still carry warnings, what `notes[]` carries, and that it is pure arithmetic with no store lookup so it answers instantly. This is exactly the added behavioral context the bar asks for.

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

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

Purpose and the store-asymmetry insight are front-loaded, and most sentences carry genuine information. It is on the long side with some digressive asides (the emoji example, the phrases explanation), but little is pure filler.

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

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

With no output schema, the description fully carries the return contract: per-field length as the store counts it (UTF-16 code units), the limit, remaining, warnings[] with levels and rule names, valid, notes[], and the iOS keywords object. Nothing an agent needs to interpret results is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: kw_field is iOS-only and Google Play has no such field (surfaced via notes[]), subtitle means subtitle on iOS vs short description on GPlay, and it explains the iOS keywords return shape (phrases, duplicates, wasted_on_spaces). It stops short of documenting length limits per field, which it only references generically.

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

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

States a specific verb+resource ('Check draft listing text against the stores' own rules') and immediately positions it relative to the sibling simulate_metadata. 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?

Explicit sequencing: run this 'before spending a run measuring it', 'on every draft you write, in a loop if that helps, and call simulate_metadata only once it comes back valid.' Names the alternative and the condition that selects it.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond that: it scopes the result to the current billing period and clarifies the counts are used-vs-allowed. It stops short of noting caching, refresh timing, or whether the call itself consumes quota.

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

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

A single dense sentence with zero filler; the core purpose is front-loaded and the metric list follows as supporting detail. Nothing in it is redundant with the title.

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

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

With no output schema, the description carries the return-value burden, and it does so by enumerating every metric reported (applications, keywords, competitors, inspections, niche analyses, autocomplete queries, metadata simulations, API requests). An agent knows exactly what it will receive without opening a schema.

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

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

The tool takes no parameters, so there is nothing to disambiguate and the description correctly adds no parameter guidance. Baseline for a zero-param tool is 4.

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

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

States a specific verb (Get) and resource (current account usage and plan limits), then enumerates the exact metrics returned. It is cleanly distinguishable from every per-resource sibling like list_applications or inspect_keyword, since it is the only aggregate-usage 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?

Usage is implied — call it to check consumption against plan limits for the current billing period — but the description never states when to prefer this over siblings or what triggers a need for it (e.g., before bulk operations or quota errors). No exclusions or alternatives are given, though none are strongly needed for a zero-arg aggregate tool.

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

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

Annotations already declare a safe read-only, non-destructive operation, and the description adds substantial context beyond them: null scores on days without snapshots, default 30-day window, 400-day cap, plan history depth with PLAN_LIMIT error, date reversal swapping, and future-date clamping. This is unusually rich behavioral disclosure.

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 purpose and score definition, then return shape, defaults, limits, errors, and the sibling alternative. Dense but every sentence carries operational information; nothing is filler.

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

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

With no output schema, the description correctly documents return values (app_id, app_title, resolved from/to, history[] shape). Error behavior, caps, defaults, and parameter caveats are all covered, so an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine value beyond the schema by warning that app_id must be the numeric internal ID from list_applications rather than the store bundle ID, and by restating the from/to defaults and date semantics. It does not add format details for from/to beyond what the schema already says.

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 daily visibility score history of one application') and defines what the score means (0-100 discoverability across a stable keyword set). It explicitly distinguishes itself from the sibling get_keyword_rank_history, so an agent can route correctly without opening either schema.

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

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

Gives an explicit alternative and the condition that selects it ('For one keyword rank over time, use get_keyword_rank_history'), plus a prerequisite: use the numeric internal ID from list_applications, not the store bundle ID. When-to-use is unambiguous.

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

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

Annotations cover the safety profile (readOnly, non-destructive, non-open-world), and the description adds substantial behavior beyond that: the result is a stored, auto-updated audit answering in milliseconds, report is null when the audit never reached the app ('which is not a score of zero'), and fields[].text is a truncated preview with the full text living on list_applications.

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 and alternatives before the dense reference material, and nearly every sentence carries distinct semantic content (axes, tiers, state values, truncation, null-vs-zero). It runs long and repeats some schema content, and a few asides ('Say that when you explain a verdict', store-name phrasing) are advisory rather than definitional, but it is not padded.

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

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

With no output schema, the description carries the full burden of describing the return shape and does so thoroughly: app identity fields, global score, three axes, maturity tier, fields[] states including the unpublished iOS keywords field, targeting verdicts and counters, assessable, and the null-report case.

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

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

Schema coverage is 100% and the schema already documents app_id and include_words in depth, so the baseline is 3. The description nonetheless adds meaning the schema lacks: that field/verdict semantics (state values, tier-dependent verdict thresholds, ungraded/unsearched counts) shape what include_words returns, and it reinforces why include_words is off by default.

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

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

States a precise verb+resource ('Get the full ASO Health audit of one tracked app') and immediately scopes it against the sibling concern of ranking: 'how well its listing is WRITTEN, as opposed to how it currently ranks.' It also enumerates the return payload, so an agent knows exactly what this tool yields versus other app 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 routes to alternatives with conditions: get_app_score_history 'for visibility over time' and simulate_metadata 'to score a listing that does not exist yet.' It also states a usage property ('call it as often as you need') grounded in the cached/stored nature of the result.

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

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

With readOnlyHint/destructiveHint already declaring safety, the description still adds substantial behavior: 30-day default window, 400-day and plan-depth cap, PLAN_LIMIT error, reversed-date swapping, future-date clamping, and null ranks on non-ranking days. Strong disclosure, though it doesn't cover pagination or result-size 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?

Dense but front-loaded with the core purpose and return shape, and each sentence carries real information (defaults, caps, error, date normalization, sibling route). Slightly long as a single block of sentences, but 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?

No output schema exists, so the description compensates by describing the returned fields and history[] entries in detail, plus the edge-case behaviors an agent needs. Nothing essential is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns more by explaining that reversed dates get swapped, future dates are clamped, and app_id narrows rather than filters the series — semantics the schema only hints at. Minor duplication of the 'from list_keywords' note already in the schema.

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

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

States a specific verb and resource ('Get the daily rank history of one tracked keyword') plus the output shape. It explicitly names the sibling it is not (get_app_score_history) for the whole-app case, so an agent can disambiguate without opening schemas.

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

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

Tells the agent where keyword_id comes from (list_keywords), how to narrow output (app_id), and gives an explicit alternative plus the condition that selects it ('for the visibility of a whole app rather than one keyword, use get_app_score_history').

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), and the description adds 'instant' latency context plus a breakdown of the returned payload, which matters because no output schema exists. It stops short of describing size limits or pagination, but for a single-read tool this is solid added context.

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

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

The purpose is front-loaded, but the middle clause ('This is what list_metadata_simulations cannot carry, and it is what makes a past run worth picking up: the text is here') is rhetorical filler that does not add selection or invocation value. The definition is longer than the task requires.

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

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

With no output schema, the description usefully enumerates the returned contents and confirms the operation is read-only and instant, which is enough for an agent to call it correctly. Minor gaps remain around payload size or field formatting, but nothing essential 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 schema already documents that id is the saved run id from list_metadata_simulations or simulate_metadata's saved.id. The description restates the same provenance without adding format nuances beyond the schema, so the baseline 3 applies.

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

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

States a precise verb and resource ('Read one saved listing draft in full') and enumerates exactly what comes back: the four scored fields, assumed context, score, and findings. It explicitly contrasts with the sibling list_metadata_simulations, so an agent can distinguish the two 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 names where the id comes from — a row of list_metadata_simulations or simulate_metadata's saved.id — which is the practical prerequisite for calling it. It implies the use case (recovering the full text of a past run) but gives no explicit when-not or exclusion guidance.

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

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

The annotations declare readOnlyHint=false and openWorldHint=true, and the description adds important behavioral context: inspection can consume an inspection quota, unless the keyword is already tracked. It also enumerates the returned data, which is necessary because no output schema exists. It does not discuss permissions or idempotency, so it is 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 purpose is front-loaded, and the two sentences are dense but mostly earn their place because the tool has no output schema and needs to advertise its return fields. The return-value list is long, but it is useful for agent selection and invocation.

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

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

Given the absence of an output schema, the description thoroughly explains what the tool returns and includes the important quota nuance. It is largely complete for an agent to call it correctly, though it does not address when to prefer it over sibling tools, which is a usage-guideline gap rather than a completeness failure.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds only marginal semantic detail by implying that the keyword parameter can refer to an untracked keyword, but it does not explain store, country, or lang beyond what the schema already 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 states a specific verb and resource: 'Deep-analyze any keyword (even ones you don't track).' The scope is clear, including that the keyword need not be tracked. It does not explicitly differentiate this tool from sibling analysis tools like run_niche_analysis or run_autocomplete, so it falls short of a 5.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no named alternatives. The note about tracked keywords and quota is contextual but does not tell the agent when this tool should be selected over siblings such as run_autocomplete or list_keyword_inspections.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint, openWorldHint), yet the description adds real value: it enumerates the returned fields, explains the null case for aso_health, and points to get_aso_health for the breakdown. The trailing 'Read-only' duplicates the annotation, but the null semantics and downstream-ID behavior are non-obvious context.

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

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

Purpose and workflow positioning are front-loaded, and the long field enumeration earns its place given there is no output schema. Slightly dense, but no redundant sentences beyond the 'Read-only' tail that the annotations already assert.

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 return-value burden and does so thoroughly (fields, null behavior, pointer to the detail tool). It also supplies the cross-tool ID contract, which is the key thing an agent needs to chain calls correctly.

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

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

Schema description coverage is 100% and the single app_id filter is fully documented there, so the baseline is 3. The description never mentions the filter at all, so it adds nothing beyond the schema on this dimension.

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

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

States a specific verb+resource ('List all tracked mobile applications') and immediately differentiates itself from the closest sibling by noting that add_application takes the store bundle ID while this tool returns the numeric internal ID. An agent can distinguish it without opening any 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 positions the tool as 'usually the first call of a workflow' and names the downstream consumers (track_keywords, add_competitor, get_app_score_history, other app-scoped tools). It also contrasts input conventions with add_application, giving both when-to-use and when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful context by naming the returned fields, but says nothing about pagination behavior, ordering, or result limits beyond what the schema covers.

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

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

A single front-loaded sentence that names the resource, its scope, and its returned fields without any waste. Every clause earns its place.

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

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

For a simple read-only list tool with full annotation coverage and full schema coverage, the description is close to complete and even compensates for the missing output schema by listing the returned fields. Only minor pagination/ordering context is absent.

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

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

Schema description coverage is 100% and both parameters (page, per_page) are documented in the schema, so the baseline is 3. The description adds no pagination syntax or format detail beyond that.

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 autocomplete queries') with a clear scope qualifier ('previously run'), and enumerates the returned fields. It implicitly distinguishes itself from run_autocomplete but never names that sibling or any other alternative, so it falls short of a 5.

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

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

There is no explicit when-to-use guidance, no mention of prerequisites, and no routing to alternatives like run_autocomplete or list_niche_analyses. The past-tense 'previously run' is the only usage signal, which the agent must infer.

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

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

With no output schema, the description carries the return-value burden and does so well, enumerating the exact fields per pair and the app_score/competitor_score comparison semantics. Annotations already cover read-only/safe-profile, so this adds genuine behavioral context rather than repeating it.

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

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

Front-loaded with the verb+resource, then a structured enumeration of pair contents. The field list is dense but informative given the absent output schema; only minor trimming would be possible without losing return-shape clarity.

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

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

For a read-only list tool with no output schema, the description adequately explains the return structure, score semantics, and the sibling alternative. It doesn't describe pagination or empty-result behavior, a minor gap given the simple closed-world read.

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 there is one optional param, so the schema already documents app_id fully. The description adds no filter semantics beyond the schema-provided numeric example, making this baseline-level.

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), then details exactly what a pair contains. It also explicitly distinguishes itself from list_applications, so an agent can separate it from the many siblings without opening schemas.

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

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

Explicitly routes the agent to list_applications for the user's own app metadata, which is clear context. It stops short of stating when to prefer this over add_competitor/remove_competitor or the filtering effect of app_id, so it's clear but not fully exhaustive.

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

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

Annotations already establish readOnly/non-destructive/closed-world, so the safety profile is covered. The description adds real behavioral value by promising the operation does not consume inspection quota and by naming the returned fields, which is beyond what the annotations provide.

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

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

One tightly written sentence that front-loads what is listed and then adds the value proposition. No filler.

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

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

With no output schema, the description helpfully enumerates the returned fields and notes the quota benefit. Only minor gaps remain, such as ordering of results and pagination behavior, which an agent could infer from the schema.

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

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

Schema coverage is 100%, so page and per_page are already fully documented (including max 200 and default 50). The description adds no pagination or ordering detail, 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 (List) and resource (previously inspected keywords) and enumerates what is returned (last inspection date, difficulty/traffic scores). The word 'previously' distinguishes it from list_keywords, though it never names that sibling explicitly.

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

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

Gives a clear use context: revisit past keyword research without re-consuming the inspection quota. It does not explicitly contrast with inspect_keyword or state when NOT to use it, but the quota-avoidance rationale is a solid usage signal.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds substantial behavioral context beyond them: null-rank semantics ('not ranked', never 'unknown'), the guarantee that the tool errors out rather than returning partial rank data, pagination, and the meaning of ahead/behind. This is exactly the extra context annotations cannot convey.

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

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

Front-loaded with purpose then return shape, and the null-rank caveat is placed right after the field it qualifies. The long field enumeration is dense but each item is informative; only minor trimming is possible.

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

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

With no output schema, the description correctly carries the return-value burden and documents fields, null behavior, error behavior, and pagination. The remaining gap is usage routing against the many sibling list/rank tools, which is not addressed.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description adds no parameter-level detail (no mention of page/per_page defaults, app_id filtering, or the favorites flag), 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 ('List tracked keywords with ASO metrics') and enumerates the exact fields returned. However, it never differentiates itself from close siblings such as inspect_keyword, list_keyword_inspections, or get_keyword_rank_history, so an agent must infer the boundary.

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

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

Usage is only implied by the name and the paginated-list shape; there is no explicit when-to-use, when-not-to-use, or named alternative. The description does not mention the app_id/favorites filters as usage guidance, and no routing to inspect_keyword or track_keywords is given.

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

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

Annotations cover the safety profile (readOnly, non-destructive, non-open-world), and the description adds substantial context beyond them: exact row composition, the fact that only the TITLE is included, that subtitle/keywords/description are omitted, and how to retrieve the omitted fields. This is unusually rich disclosure for a list tool.

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

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

Front-loaded with scope, then return contents, then the routing hint. The middle inventory sentence is long but each field listed earns its place given there is no output schema. No filler sentences.

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

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

With no output schema and no docs beyond the description, the description carries the return-value burden itself and does so completely: scoping, ordering, row contents, omissions, and the follow-up call. 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 description coverage is 100%, so page, search and per_page are already documented in structured data, and the description adds nothing about them. It does clarify the semantics of the returned `id` field as an input to get_metadata_simulation, which is mild added value but not parameter-level detail.

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

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

States a specific verb and resource ('list the listing drafts already scored on this account') plus scope details: newest first, includes runs from both the API and the dashboard. It is clearly distinguishable from sibling get_metadata_simulation, which it names as the full-detail counterpart.

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 the use case ('find a past score without re-running it') and names the alternative tool for reading a draft in full. It doesn't spell out when not to use it (e.g., versus simulate_metadata for fresh runs), so it falls just short of full when/when-not coverage.

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

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

Annotations already convey readOnlyHint/destructiveHint, but the description adds real value: it explains that it re-reads previously completed work, describes pagination behavior, and states the return scope is 'summary rows only, not the clusters and keywords themselves' — an important limit not in any structured field. Minor gaps (no rate limits or auth notes) keep it from 5.

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

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

Three sentences, each doing distinct work: what it lists, pagination, and the usage/return-scope caveat. Front-loaded with the resource and returned fields; zero filler.

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

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

With no output schema, the description compensates by naming the returned fields and clarifying that cluster/keyword detail is excluded, so an agent knows exactly what a call yields. Combined with the pre-run check guidance, nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100% and both parameters (page, per_page) are documented with defaults in the schema. The description only restates that pagination happens through page and per_page, adding no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('List the niche analyses previously run') and enumerates the returned fields (topic, store, country, lang, cluster count, keyword count, top opportunity score, creation date), which distinguishes it clearly from siblings like run_niche_analysis and list_keywords.

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

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

Explicitly tells the agent when to call it: 'call it before run_niche_analysis to check whether a topic was already covered.' Names the alternative tool and the condition that selects this one, with 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?

Annotations already declare readOnlyHint=true, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond that by describing the shape of the returned data (categories and collections) and giving real example key values, which helps the agent understand what it will get back.

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 waste, front-loaded with the core action before the downstream usage note. Every clause earns its place.

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

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

No output schema exists, but the description compensates by explaining what is returned (categories and collections with usable keys) and how those keys feed top_charts. Complete enough for a single-parameter lookup tool; minor gaps on return format/pagination remain.

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 enum parameter already documents 'Filter to one store; omit to get both'. The description's 'per store' phrasing adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List the categories and collections supported by the top_charts tool, per store') and implicitly distinguishes its role from the sibling top_charts (this is the discovery/input tool, top_charts retrieves the charts). An agent can tell the two apart without opening either schema.

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

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

Gives concrete downstream usage: pass a returned category key (with examples like "OVERALL", "6014", "GAME") plus a collection (free, paid, grossing) into top_charts. It clearly establishes the call-order context but does not state when-not to use it or name alternative paths.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety and repeat-call profile is covered. The description adds the useful disambiguation that the argument is a relation row id rather than a competitor app id, but says nothing about effects or reversibility beyond what annotations provide.

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

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

A single front-loaded sentence identifies the action and identifier, with the clarification parenthesized rather than padding the main clause. No wasted words.

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

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

For a one-parameter delete tool with no output schema and full annotation coverage, the description supplies everything an agent needs: what it does, what it deletes, and precisely which ID to supply.

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 would be 3, but the description goes further by warning that the id is the relation row id and not the competitor app id, resolving a genuine ambiguity the schema alone does not address.

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 (remove) and resource (competitor relationship) and clarifies the identifier to use. It draws a sharp distinction that lets an agent differentiate it from sibling tools 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?

It tells the agent where the required ID comes from (the `id` field returned by list_competitors or add_competitor), which is clear usage context. It does not, however, state when not to use it or any prerequisites such as permissions.

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 a metered-cost disclosure ('Consumes one autocomplete query and one API request'), which is exactly the kind of context annotations cannot express and which explains the non-read-only, non-idempotent hints. It does not describe the returned suggestion structure or any rate-limit behavior, so it is useful but not complete.

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

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

Three short sentences, front-loaded with the action and resource, then the purpose, then the cost. No filler, though the third sentence could be folded into the second without loss.

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

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

For a read-oriented lookup with a fully documented four-parameter schema, the definition covers action, input constraint, intent, and quota cost. The only gap is the absence of any statement about what the response contains, which matters slightly because no output schema exists.

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 all four parameters (store enum, country, lang, prefix) documented in the schema. The description repeats the prefix length bound and store sources but adds no format or semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Fetch autocomplete suggestions from the App Store or Google Play for a given prefix') plus the input constraint (1-60 chars). Clear on its own, though it never explicitly distinguishes itself from the sibling list_autocomplete_history, leaving the live-fetch vs. stored-history distinction to inference.

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

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

'Useful to discover what users are searching for that starts with a given seed' gives a use context, but there is no when-not guidance and no named alternative. An agent must infer that this is the live lookup rather than the historical listing.

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

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

Annotations give the safety profile (readOnlyHint false, openWorldHint true, non-idempotent, non-destructive), and the description adds genuinely new behavioral context: quota consumption on cache miss, instant cache hits, and multi-minute latency. It stops short of describing auth/permission requirements or what happens on partial failure.

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

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

Three sentences, front-loaded with the action, then the result shape, then the cost/caching notes. Efficient, though the opening 'Run a niche analysis on a topic' partially restates the title before adding new information.

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

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

There is no output schema, and the description compensates by enumerating what is returned (clusters, keywords, opportunity scores, intent type, app concept suggestion). Combined with the latency and quota notes, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so all four parameters (topic, store, country, lang) are already fully documented in the schema, including the enum for store. The description contributes no additional parameter semantics, so the baseline of 3 applies.

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

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

States a specific verb (run) and resource (niche analysis on a topic) and unpacks the internal workflow: keyword discovery, clustering into sub-niches, opportunity scoring. It is clearly distinguishable from the sibling list_niche_analyses, which merely reads history.

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 discloses quota consumption, caching (identical analyses under 7 days return instantly), and latency (a few minutes), which helps an agent decide whether the call is cheap. However, it never names when to prefer this over siblings like list_niche_analyses or run_autocomplete, so usage is only implied.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful semantics beyond that: favorites are stored per tracking row (profile + app + keyword), so a keyword across multiple apps has independent states. That clarifies blast radius and idempotency 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?

Three tight sentences, zero waste, with the action and scope front-loaded and the per-row storage model following. Every sentence contributes distinct information.

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

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

With annotations carrying the safety profile, full schema coverage, and no output schema, the description supplies what an agent needs: the action, the per-row scoping model, and where arguments originate. Only a minor gap remains in not naming related alternatives.

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 each parameter already documents its type and source, so the schema does the heavy lifting. The description reinforces that IDs come from list_keywords but adds no format or syntax detail beyond the schema; baseline 3 is appropriate.

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

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

States a specific verb (mark/unmark), resource (tracked keyword), attribute (favorite), and scope (for a specific app). It is clearly distinguishable from siblings like track_keywords and inspect_keyword, and the state-toggle semantics are explicit.

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

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

Gives clear prerequisite context: both keyword_id and app_id come from list_keywords results, which tells the agent where to source inputs. It does not name an alternative or a when-not condition, so it falls short of a 5, but the usage context is well set.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and no destructiveness; the description goes well beyond that. It discloses latency ("a few seconds per call"), cache-warming behavior via words_fetched, the null semantics of delta and per-axis deltas, the deliberately floored appeal axis in draft mode, and notes[] for non-fatal request issues such as a kw_field sent for Google Play.

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 long (roughly 300 words), but front-loaded with the core purpose and mostly non-redundant: modes, return shape, latency, and sibling routing each earn their place. Some sentences, such as the extended words_fetched/words_probed explanation, could be tightened without losing information.

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

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

There is no output schema, so the description must describe returns, and it does so thoroughly (app, aso_health with three axes and tier, delta, flags, saved run, notes, words_probed/words_fetched). For a 9-parameter tool with a nested context object and no required fields, this covers everything an agent needs 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: app_id "fills every field you omit", its score is the delta baseline, context keys override while omitted keys inherit the app value (or the blank default), and one key alone enables a what-if. That merge/override semantics is not spelled out in the schema itself.

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 opening sentence states a specific verb and resource with a precise scope: score a not-yet-existing listing on the same engine that audits real ones and report the delta against the app's current score. It is immediately distinguishable from check_metadata (which validates a draft) and from the get/list metadata_simulation siblings that merely retrieve runs.

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 mode-selection rules (WITH app_id vs WITHOUT app_id), states the question this mode answers ("is my draft better than my listing"), warns you must not present the no-app_id score as comparable, and routes to siblings: "Check the draft with check_metadata first", get_metadata_simulation to re-read a run, list_metadata_simulations to list them. It even advises changing something meaningful between calls rather than polling.

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

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

Annotations already declare readOnly/openWorld/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it enumerates the returned fields (rank, delta vs. yesterday, is_new), states the snapshot date is included, and documents defaults for category and collection. It does not discuss rate limits or caching, so it stops short of a 5.

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

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

The definition is front-loaded with the core purpose, then the return payload, then parameter semantics — a sensible order. The parameter sentences are somewhat verbose for a tool whose schema already documents those fields, costing it a point.

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

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

There is no output schema, so the description carries the return-value burden and does so by listing the ranked-app fields and the snapshot date. Combined with 100%-documented parameters and full annotations, nothing an agent needs to invoke this tool correctly is missing.

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

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

Schema description coverage is 100% and both enums are documented in the schema, so the baseline is 3. The description largely restates the schema's category and collection text (including the same '6014'/GAME examples) rather than adding new format or interaction detail, so it does not exceed the baseline.

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

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

The description opens with a specific verb+resource ('Get a store top-chart ranking') and immediately bounds it by store, country, category and collection. It is clearly distinguishable from siblings such as list_top_chart_categories (which enumerates categories) and get_keyword_rank_history (which is keyword-scoped).

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 context is implied through the parameter explanation (category/collection choices) but there is no explicit statement of when to prefer this tool over siblings like list_top_chart_categories, nor any exclusions or prerequisites. An agent can infer the use case, but the guidance is not 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 already cover the safety profile (readOnlyHint=false, destructiveHint=false), and the description adds genuine behavioral context beyond them: each keyword triggers an immediate ranking fetch (a cost/side effect), duplicates produce per-keyword errors in `results` rather than failing the call, and removed keywords are reactivated automatically. These side-effect and partial-failure semantics are exactly what an agent needs before calling a non-idempotent mutation.

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

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

Four tight sentences, each carrying distinct information: operation scope, side effect, duplicate/error handling, reactivation, and the required ID source. The most decision-relevant fact (immediate ranking fetch) and the cap are front-loaded with no wasted prose.

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 explains the return surface by naming the `results` field and its per-keyword error content, and it covers the mutation's side effects and edge cases. For a 5-required-param mutation tool, nothing essential to correct invocation 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%, so all five parameters are documented in the schema itself. The description adds only the 20-keyword cap (already in the schema's maxItems) and repeats the app_id provenance note, so it does not meaningfully extend parameter meaning. 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 ('Track up to 20 new keywords for one of your applications') with an explicit scope cap, clearly distinguishing it from siblings like untrack_keyword and list_keywords. An agent can identify the operation without opening the schema.

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

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

Gives a clear usage condition (adding new keywords) and a concrete prerequisite ('Use app_id from list_applications results'), plus edge-case behavior for already-tracked and previously removed keywords. It stops short of explicitly naming untrack_keyword as the inverse alternative, so it is one step below full when/when-not guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: the delete is soft, historical ranking data is preserved, and re-adding reactivates the same row, which materially changes how an agent reasons about data loss. It does not cover permissions or rate limits.

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

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

Three short sentences, front-loaded with the action and its soft-delete nature, then the data-preservation consequence and the idempotency guarantee. No filler.

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

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

For a simple two-parameter mutation with no output schema, the description covers the behavior an agent needs: what happens to the row, what happens to history, and what a repeat call returns. Only the absence of any access/permission expectation keeps it from being fully complete.

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

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

Schema description coverage is 100% and both parameters are documented as internal IDs sourced from list_keywords, so the schema already does the work. The description adds no syntax, format, or edge-case meaning beyond it, making 3 the correct baseline.

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

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

States a specific verb and resource ('Stop tracking a keyword') scoped to an app, and explicitly frames it as a soft delete distinct from the hard-removal an agent might assume. An agent can separate this from track_keywords 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?

The description implies context (untracking an existing tracked keyword, re-adding via track_keywords to reactivate) but never states when to use this tool versus alternatives or any prerequisite that the keyword must currently be tracked. Usage is inferable rather than stated.

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