AppTail – ASO & Keyword Research

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

Annotations only declare readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description goes further, disclosing the immediate side effect (rankings, reviews, competitors begin tracking at once), the billing/plan implication, and an out-of-band dependency (App Store Connect must be connected in the console, not here). That is exactly the behavioral context annotations cannot carry.

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

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

Three sentences, front-loaded with the core action, then input forms, then side effects and the ASC limitation. No sentence is filler; each adds a distinct fact an agent needs.

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?

Safety profile comes from annotations and return shape from the output schema, so the description's job is side effects and prerequisites — both covered. Nothing an agent needs to call this mutating, importing 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 coverage is already 100%, so the schema sets the floor at 3. The description adds cross-tool semantics by stating all three accepted forms are resolved and imported the same way search_apps resolves them, which tells the agent the input is a resolution target rather than a raw key.

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 ('Add an app to the account as one of the user's own') and pinpoints the accepted input forms (app_id, App Store URL, or name). It also distinguishes itself from the sibling search_apps by noting resolution happens 'the way search_apps does', so an agent can tell importing apart from merely searching.

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 context: tracking starts immediately, and measured downloads/proceeds require connecting App Store Connect in the console, which 'cannot be done from here' — a real prerequisite. It stops short of an explicit when-not-to-use rule or naming an alternative tool for the pre-check (dry_run covers that only inside the schema).

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 (readOnly=false, destructive=false, openWorld=true), and the description adds meaningful behavior beyond them: per-item outcome reporting, plan-limit refusal semantics, and that a batch still adds what fits. Good added context on partial success and limit handling.

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

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

Three sentences, front-loaded with the core action, then resolution behavior, then return semantics. Every sentence earns its place with no redundancy.

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

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

An output schema exists so return values needn't be spelled out, yet the description still summarizes the per-item outcome structure. Combined with the workflow guidance on avoiding a prior app_id lookup, an agent has everything needed to invoke 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 the schema already documents app_id, country, dry_run, and competitors. The description mostly reinforces that resolution accepts app_id/URL/name, which the schema already states; 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+resource ('track rival apps against one of YOUR apps') and distinguishes itself from get_competitors/remove_competitors by being the add side of competitor tracking. It also clarifies the relationship to search_apps for name/URL resolution.

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 it does NOT need to look up an app_id first because names/URLs resolve like search_apps, which is the key workflow decision. It does not name explicit when-not conditions versus siblings, 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 only say it is a non-destructive write in an open world; the description goes much further by disclosing plan-limit consumption, the no-write guarantee of dry_run, the idempotent 'already_tracked' outcome, and the immediate-crawl/unmeasured read-after-write 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?

Purpose is front-loaded in the first clause, and the remaining sentences each carry a distinct operational fact (id requirement, quota, dry_run, already_tracked). No filler despite the density.

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-parameter mutation with an output schema already handling return shape, the description covers everything an agent needs: quota implications, batching guidance, id ambiguity, dry-run semantics, and the non-error duplicate 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 its field descriptions are already detailed, so baseline is 3. The description still adds cross-cutting semantics the schema cannot: that a re-resolved term can land on a different keyword row, justifying the id-vs-term choice, though it adds little on app_id/country/dry_run.

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+scope: 'Start tracking search terms for one of your apps, in one storefront.' It is immediately distinguishable from siblings like discover_keywords (suggestion source) and remove_keywords (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?

Gives explicit routing rules: send terms OR keyword_ids from discover_keywords, with the hard condition that a suggestion MUST be added by id. Also flags the plan limit, the dry_run escape hatch, and that already-tracked terms are not an error.

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=false, openWorldHint=true, destructiveHint=false. The description goes further, disclosing the actual side effects — persisting shared suggested keyword records, caching suggestions, queueing background popularity collection — and clarifies the boundary that it does not modify account tracking.

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 with the core definition and the get_landscape alternative before the caveats. It runs long for a single description and repeats a few points already in the schema, but nearly every sentence carries decision-relevant information.

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

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

An output schema exists, so return values need no explanation. The description still covers all the complexity an agent needs: the five default sources, why corpus is excluded from 'all', the never-returned already-tracked/dismissed terms, and the per-storefront constraint.

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 beyond the schema: `listing` is the only source that can surface an unranked phrase and only when two-plus rivals publish it, `corpus` requires `contains`, and storefront selection is never a blend. Some of this duplicates the schema text, hence not a 5.

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 — unearthing candidate terms an app could track but is not — and enumerates the provenance of each candidate. It is clearly distinguishable from get_keywords (tracked terms) and get_landscape (coverage gaps), which it names 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?

Routes the agent to siblings by condition: get_landscape/`term_gap` for coverage measurement, add_keywords to actually track a new term, and it explicitly states discovery does NOT add terms to tracking. It also tells the agent to call once per storefront using get_app's `listing_storefronts`.

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 flag destructive=true, but the description adds substantial context beyond them: pinned terms survive every rebuild and refresh on a 72-hour cadence, removed heuristic terms are recorded as excluded so they don't re-derive, and a later `add` clears that exclusion. These are non-obvious side effects an agent cannot infer from the structured fields.

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 add/remove action, then the behavioral details, then the sibling contrast. Dense and mostly waste-free, though the long single paragraph carries a few stacked clauses that could be broken out.

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 an output schema present, return values need not be described. The description covers the add/remove semantics, cadence, rebuild persistence, exclusion behavior, and the differentiating contrast with `save_market`, leaving nothing an agent needs in order 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. The description goes further by framing the intent of `add` (terms the corpus should hold) versus `remove` (terms that don't belong, and the persistent exclusion effect of removing a heuristic term), adding conceptual meaning on top of the already-detailed schema descriptions.

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

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

The description states a specific paired verb (add / remove) operating on a single storefront's corpus, and explicitly names what it is not (`save_market`). An agent can distinguish it from the heuristic-rerunning seed tool 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 when-to-use conditions: add for a term the corpus SHOULD hold but doesn't (rival brand, unmeasured phrase, thin storefront's real subject); remove for a term that does not belong, noting ANY term can go. It also contrasts with `save_market`, explaining that seeds re-run the heuristic while these writes act on single terms in 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description still adds real behavioral context beyond that: output includes comparison data, coverage and caveats identifying unavailable sections, and it explicitly states reads do not change tracking or publishing content.

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 what is returned, then a second sentence on return shape and read-only behavior. The enumerated section list is long but each item earns its place by defining the aggregate; no filler or throat-clearing.

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 an output schema present, the description needn't detail return values, yet it usefully flags caveats and unavailable-section coverage. Safety is covered by annotations and all six parameters are fully documented in the schema, leaving only the missing when-to-use/routing guidance as a gap.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already explains default windows, from/to precedence, app_id scoping, and the compare enum. The description adds little parameter-level meaning beyond restating that it covers a requested period and noting per-storefront money reporting (which the schema attributes to country).

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 (Return) on a specific resource (account or owned-app summary) scoped to a requested period, with the aggregated sections enumerated: performance, storefront changes, keyword movements, signals, review volume, last digest. The aggregate role clearly separates it from single-purpose siblings like get_performance, get_signals, and get_reviews without needing to name them.

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

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

No explicit when-to-use statement, no exclusions, and no routing to alternatives such as get_performance or get_reviews when only one section is wanted. Usage is only implied by the aggregate framing plus the schema's detailed parameter guidance, which the agent must infer triggers this tool rather than a narrower sibling.

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/openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: it discloses that plan limits can refuse a write, that first-party data has a freshness dimension, and that hidden apps must be excluded from portfolio totals to keep answers consistent with the customer's console.

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 returned payload before the routing instruction. The first sentence is a dense enumeration but every item earns its place; 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?

An output schema exists, so return-shape explanation is unnecessary, yet the description still covers payload scope, the must-call-first routing role, and the consistency caveats. Nothing an agent needs to call this 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 booleans are documented with defaults and rationale, so the schema carries the burden. The description mentions hidden apps and focus storefronts but adds no syntax, default, or format detail beyond what the schema already provides; baseline 3 is appropriate.

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

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

States a specific verb+resource (get the account) and enumerates the payload: apps with Apptail ids, plan/limits, ASC health, data freshness, focus storefronts. It explicitly distinguishes itself from every sibling by noting that all other tools require an app_id obtained here.

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 routing rule — 'Call this first whenever the request is about "my app" or "my keywords"' — plus the reason (every other tool needs an app_id). It also flags that focus countries and hidden apps must be honored for answers to match the console, which is actionable invocation 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?

Offers substantial disclosure beyond the readOnly/openWorld/destructive annotations: plan gating ('ratings, charts and popularity need a Starter or Pro plan and are refused by name without one'), cost behavior ('each section is a query'), a hard cap (history_days capped at 365), and an explicit non-goal (no impressions, downloads or revenue). This is exactly the extra context annotations cannot carry.

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-loads the core answer, then layers includes, then exclusions and the alternative tool. Dense but every sentence carries routing, cost or scope information. Length is justified by a 4-parameter tool with a 7-value enum, though a few phrases ('pooled honestly') are decorative rather than 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?

Given an output schema exists, return fields need not be explained, and the description fully covers what an agent needs: scope, storefront semantics, section gating, plan requirements, cost, caps, and the excluded performance metrics. Nothing needed to call 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 coverage is 100%, so baseline is 3, but the description adds narrative meaning: `country` 'changes the answer rather than filtering it', and sections are grouped by what question they answer (e.g. `popularity` = organic reach, `versions` = release cadence). Some content overlaps the already-rich schema, preventing a 5, but it does more than echo structured fields.

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 ('Everything AppTail holds about one app') with an explicit scope boundary: the base answer is 'the store listing in one storefront', and `include` adds named sections. It also explicitly distinguishes itself from get_performance and clarifies it works for 'ANY app in the store, not only the user's own', which separates it from the user-scoped siblings.

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

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

Gives explicit when-to-use routing: get_account for the user's own apps, search_apps for any other app, get_performance for impressions/downloads/revenue. It also states when to use each include section and, crucially, when to omit them ('omit for the listing alone, which is the cheap answer'), plus which sections need a paid plan.

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=false, the description proactively discloses the non-obvious write side effects: suggestions can persist shared keyword records and queue background crawls. It also explains the crawl/listing fallback for apps without keywords — real behavioral context beyond the annotations.

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

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

The core purpose is front-loaded in the first clause, followed by the suggested-rivals explanation and the persistence/watchlist caveats. Dense but each sentence carries information; the opening sentence is long and stacks a secondary clause, costing a little 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?

An output schema exists, yet the description still points at the specific field (suggested_basis.terms_pending) needed to interpret completeness, and covers side effects and watchlist behavior. 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 coverage is 100% and the single app_id parameter is fully documented in the schema, including the get_account source and the apple_app_id distinction. The description adds no parameter-level 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+resource (list tracked competitor apps) plus the secondary output (suggested untracked rivals) and the ranking basis. An agent can distinguish this from add_competitors/remove_competitors 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?

Gives clear operational context: it works on apps with no keywords, tells you to read suggested_basis.terms_pending before treating a short list as complete, and clarifies that suggestions are not added to the watchlist. It does not explicitly name alternative siblings or state when-not to call it, so not a full 5.

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

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

Annotations already cover safety (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description focuses on behavior instead: results are sorted worst-movement-first, rows are a *selection* not a sample, and `movers`/`coverage` are counted over the whole corpus. That selection-vs-sample disclosure materially changes how an agent should interpret output. It stops short of covering pagination/rate-limit behavior, so it is strong 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?

Purpose and the sibling-replacement statement are front-loaded, and nearly every sentence carries load-bearing detail (selection semantics, sort behavior, cap of 300). It is, however, a dense wall of prose with long em-dash-chained clauses that could be broken into scannable blocks, so it is efficient but not perfectly structured.

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

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

For a 13-parameter tool with an output schema present, the description covers the decision-relevant surface: scope/app_id coupling, include-block requirements, date-window resolution, and result-selection semantics. Return-value shape is left to the output schema, which is the correct division of labor.

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 nevertheless adds interpretation beyond the schema, e.g. that `contains` is the only way to surface a mid-table term that sorting would never expose, and that `keyword_ids` still answers untracked terms under a single-app scope. These are meaning-level additions rather than restatements.

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 precise verb+resource+scope ('the account's tracked keywords for an app — or across the whole portfolio — over any window') and enumerates exactly what each returned row contains (start/end rank, movement, days held, measured days). It explicitly names the three siblings it supersedes — get_tracked_keywords, get_keyword_positions, compare_keyword_positions — so 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?

It states outright that this is the tool for every question about tracked terms and lists the alternatives it replaces. It also gives conditional guidance inline: use `contains` to ask about one term by name, `scope: portfolio` for cross-app terms, `include: history` for day-by-day data. When-to-use and what-not-to-use are both explicit.

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

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

Discloses behavior well beyond annotations: a lookup can persist a new shared keyword record and queue a background crawl that updates stored observations, and can crawl the storefront live when cached data is over a day old. This reconciles the apparent read-only framing with readOnlyHint=false, and adds the empty-result semantics (`crawled: false`, not an error).

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 what the tool returns, then input modes, then side effects. Some sentences are rhetorical rather than operational ('a rank that fell is a fact, and the results page on the day it fell is the reason'), but nearly every clause carries usable information for an agent.

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 an output schema present, return shape need not be explained. The description covers purpose, input mode selection, live-vs-recorded behavior, empty-day semantics, and the mutation side effect — complete for a 5-param open-world lookup.

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 cross-parameter constraints the schema does not: keyword_id vs keyword+country are mutually exclusive, and country is ignored with keyword_id because the term already names its storefront.

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?

Opens with a specific verb+resource+scope: 'The App Store search results for one term in one storefront, on one day: who ranked, in what order.' It is immediately distinguishable from siblings like get_keywords (tracked term metadata) and get_top_charts (chart rankings).

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

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

Explicitly routes between input modes ('pass `keyword_id` for a term you already have an id for, or `keyword` + `country` for words a user typed'), tells when to omit the date, and names the alternative sources of a keyword_id (get_keywords, discover_keywords). It also states a negative: 'It does not track the keyword for your account.'

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context on top: the niche is storefront-scoped and not blended, rows include apps 'nobody added', and the window determines which apps 'arrived or fell out'. It omits any row limit or rate-limit note, which is the only gap.

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

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

Two sentences, front-loaded with the core purpose before the term_gap detail and the sibling routing. It is dense and em-dash-heavy, making it slightly hard to scan, but every clause carries distinct information and nothing is padding.

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?

An output schema exists, so return values need not be re-explained, and the description covers scope, sibling routing and follow-up actions. The only thing an agent might still wonder — how many rows come back or whether results are capped — is left unstated, keeping this just short of full completeness.

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

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

Schema description coverage is 100%, so every parameter (to, from, app_id, period, country) is already documented in the schema with formats, defaults and override rules. The description only implicitly touches country ('one storefront') and period ('this window'), adding no syntax or meaning beyond what the schema provides. Baseline 3 is correct when 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 names a specific resource (the niche landscape around one app in one storefront) and enumerates exactly what comes back: per-app ranking counts, top-10 ownership, ratings, review flow, size, arrivals/departures, plus term_gap. It explicitly separates itself from get_competitors by stating 'This is the niche, not your watchlist,' 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 the alternative (get_competitors) and the condition that selects it ('answers the other question'), and routes the follow-up work to add_keywords for the biggest term_gap holes. It also states the scope constraint that governs use — one storefront, never blended — which tells the agent this is a per-market read.

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=false and openWorldHint=true; the description goes further by disclosing the concrete side effects of phrase research (creating shared keyword records, persisting crawled search observations) and, critically, what it does NOT persist. It also flags data provenance ("third-party rolling 30-day estimates") and that coverage/caveats are reported, which an agent needs to interpret results honestly.

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 sentences, front-loaded with purpose and invocation mode, then returns, then side effects, then data caveats — a logical order with no filler. Some sentences are dense, but each carries distinct information that is not repeated elsewhere in structured fields.

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 an output schema present and 100% schema coverage across 11 parameters, the description need not enumerate returns or per-parameter syntax; it supplies the high-level shape plus the non-obvious side-effect and provenance context. What is missing is only peripheral (auth/permission expectations, rate-limit behavior), which the annotations and schema largely imply.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters in exceptional detail (including the market_id-vs-query exclusivity and period semantics). The description restates the two modes and mentions optional corpus/movement data but adds no syntax or format detail beyond what the schema provides, 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 ("Read iOS App Store niche data") and names both invocation modes (saved market_id vs. query + countries). It explicitly distinguishes itself from the write sibling by noting it "does not save an account market," so an agent can tell it apart from save_market 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 two calling modes give implied usage context, and the caveat about not saving a market hints at save_market as the alternative. However, no sibling is named as an explicit alternative and there is no when-not-to-use guidance (e.g., vs. get_landscape or search_apps), so routing is left largely to inference.

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, destructiveHint=false, openWorldHint=false), and the description adds real behavioral context beyond them: it returns the actual reporting window, connection coverage, and caveats, and it discloses that hidden apps are excluded from the portfolio sum to match the console. It does not discuss rate limits or auth requirements beyond connection mention.

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: what it reads, what it supports, what it returns, and what it excludes. Front-loaded with the resource set and free of 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 9-parameter read tool with an output schema, this covers scope, exclusions, comparison/split capabilities, and even return caveats. Nothing material 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% with unusually rich per-parameter documentation (grain fallback behavior, period/compare semantics, split row caveats), so the schema already carries the semantics. The description only gestures at 'documented time windows', 'period comparisons' and 'breakdowns by storefront or traffic source', which adds little beyond what the schema 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 (read) and concrete resource set (impressions, store views, downloads, sales, proceeds) scoped to App Store Connect apps on the authenticated account. It is clearly distinct from mutation siblings like add_app or reply_to_reviews, though it does not explicitly contrast itself with the closest read siblings (get_signals, get_app).

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

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

Gives clear context: owned app or portfolio, documented time windows, comparisons, and breakdowns, plus an explicit exclusion ('Does not provide private analytics for apps outside the account'). It points at get_account for obtaining app ids. It stops short of naming a specific alternative tool for other kinds of reporting.

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

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

Adds meaningful context beyond the readOnly/openWorld annotations: reviews are read from the public store and exist for every app regardless of App Store Connect connection, each review carries can_reply and reply_state, and summary counts are deliberately not filtered by rating. Return value specifics are partly delegated to the output schema, so not a full 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?

Front-loaded with purpose, then progressively deeper detail. Dense but each sentence carries routing or behavioral value; the period/can_reply/reply_state sentence and a few em-dash asides are slightly overstuffed, keeping it from a 5.

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

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

Given a 9-parameter tool with a live output schema and readOnly annotations, the description covers everything an agent needs: scope, cross-tool routing, the all-period ceiling caveat, and the distinction between windowed lists and whole-history summary counts.

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 itself is unusually rich, so the baseline is 3, but the description adds selection rationale beyond it: filters map to use cases ('check a hypothesis — crash, subscription, ads'), country is a follow-up to ratings.by_country on get_app, and unanswered + rating [1,2] is the work queue.

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 ('Reviews for any app over a window') plus the filterable dimensions and the aggregate shape returned. It distinguishes itself from siblings by naming get_app, search_apps, get_account and reply_to_reviews and clarifying the read-yourself framing.

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 routing: 'this is the tool for "what are people complaining about"... rather than asking for a summary', 'get_account for the user's own apps, search_apps for any other', and '`reply_to_reviews` is what answers them'. It also gives when-not guidance for the country filter (one storefront is a thin sample).

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 bar is lower, yet the description adds real context: it is a stored table read (cheap, reliable), it covers the user's own apps plus competitors tracked under them, and a rival's finding never asks_action. It does not discuss rate limits or pagination beyond the schema-stated cap. Solid added value, 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 scope and the cost/reliability rationale are front-loaded, and the enumeration of finding types is dense but useful. A few sentences carry rhetorical flourish ('how an assistant stops being believed') that is informative but slightly padded for a tool description. Still efficient overall.

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 an output schema present, return-value detail is not required, and the description covers scope (own apps + tracked competitors), cost profile, filtering behavior and the meaning of severity vs asks_action. Nothing an agent needs to invoke it is missing, though it could be tighter about interaction with sibling 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%, so every one of the 8 parameters is already fully documented with defaults, formats and precedence rules. The description adds no per-parameter syntax or meaning beyond that, so the baseline 3 applies — 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 states concretely what the tool returns: stored findings such as rank moves, chart entries, review spikes, competitor releases, price changes, plus own-app traffic/conversion shifts. That is far more specific than the tool name and lets an agent distinguish it from performance/history tooling. It does not, however, name a sibling tool it should be preferred over, so 4 rather than 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?

It gives a clear selection rationale against a competing approach ('This is a stored table read, not a reconstruction, so it is both cheaper and more reliable than diffing rank histories yourself'). The include_sent parameter note also supplies conditional guidance ('Set it whenever you are about to summarise a period'). It stops short of explicit when-not-to-use or sibling routing, so not a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so safety is covered. The description itself adds nothing behavioral — the genuinely useful traits (fallback to US, unrecognised values silently ignored, echoed storefront) live in the schema, not here.

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 with no waste. It is tight, though arguably too terse for a five-parameter tool with non-obvious fallback semantics.

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?

An output schema exists so return values need not be explained, and annotations cover the safety profile. The remaining gap is usage/routing guidance, which the description does not supply for a tool with many overlapping read siblings.

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

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

Schema description coverage is 100% and each parameter is documented in detail, including defaults, caps, and fallback behavior. The description merely names store/country/category without adding syntax or format meaning 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?

Clear verb+resource: 'Get top app charts' with the chart-type dimension spelled out. It does not distinguish itself from siblings like get_landscape or get_performance, which an agent might reasonably confuse for chart/ranking 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?

No when-to-use guidance, no prerequisites, no named alternatives. An agent is left to infer that this is the tool for store ranking questions rather than, say, get_landscape or get_app.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description nevertheless adds real context by specifying what is read ('saved account configuration and market observations') and explicitly ruling out create/update/delete, which is more than the annotations alone 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?

Three lean sentences, front-loaded with what is listed and followed by the read-only guarantee and the id hand-off. The enumerated field list is slightly redundant given an output schema exists, but nothing is padded or buried.

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 low-risk read tool with annotations covering safety and an output schema covering return shape, the description is nearly complete. The remaining gap is operational detail such as pagination, ordering, or behavior when the account has no saved markets.

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

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

Schema description coverage is 100%, with detailed per-parameter text for to, from and period including defaults and precedence rules, so the schema carries the parameter burden. The description only vaguely alludes to 'the requested period' and adds no syntax or precedence detail beyond the schema, which is the correct baseline of 3.

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

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

States a specific verb and resource ('List markets saved by the authenticated account') plus the scope of what is returned, so the agent knows exactly what this produces. It also implicitly distinguishes itself from the singular sibling get_market by noting the returned ids feed into it.

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 clear: call this to enumerate saved markets for a reporting window, and the note that returned ids work with get_market routes the agent to the follow-up call. There is no explicit statement of when not to use it (e.g., versus get_landscape or get_performance for aggregated metrics), so it stops short of a 5.

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

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

Going beyond the annotations, it discloses that name/URL resolution may query the public App Store and import shared app records (a real side effect), that write authorisation is required, and that one outcome is returned per item. These add genuine behavioral context, though reversibility of the deletion is not addressed.

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 action is front-loaded in the first sentence, followed by input forms, side effects, scope, and auth requirements in a compact five-sentence block. Every sentence carries information, though there is minor overlap between the body and the schema.

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 destructive, open-world mutation with an output schema present, the description covers the key agent concerns: scope, side effects, auth, and per-item results. Return-value details are correctly left to the output schema, so the only minor gap is the lack of note on how failures per item are surfaced.

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

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

Schema description coverage is 100%, so the schema already documents both parameters thoroughly, including the id/URL/name forms and the 'up to 20' limit. The description largely repeats the accepted input forms rather than adding new meaning, so the baseline of 3 is appropriate.

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

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

States a specific verb (remove), resource (competitor tracking relationships), and scope (for an app owned by the authenticated account). An agent can immediately distinguish this from add_competitors and get_competitors 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?

The description clarifies that only the selected pairing is removed and that public apps and other apps' pairings remain, which tells the agent what this tool will and won't affect. It does not explicitly name sibling alternatives like add_competitors, but 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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful context beyond them: removal frees plan slots and position history is preserved, so re-adding does not reset progress. It stops short of stating auth requirements or that removal is immediate/permanent for the tracking row.

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 short sentences with zero waste, front-loading the action and resource before the consequence. Every clause carries information about effect or data retention.

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 destructive two-param tool with full schema coverage, annotations, and an output schema, the description supplies the key behavioral facts an agent needs (slot freeing, history retention). It is essentially complete, though a note on whether the action can be undone server-side would close the last gap.

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

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

Schema coverage is 100%, so both parameters are already fully documented, including the app_id vs apple_app_id distinction and the ids-not-terms caveat. The description merely echoes the keyword_ids semantics, adding no meaning 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 ('Remove') and resource ('tracked keywords') scoped to an app, which cleanly separates it from siblings like remove_competitors, remove_market, and add_keywords. An agent can identify the tool's function 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 implied by the effect statement ('frees the slots against the plan limit'), but there is no explicit when-to-use guidance, no mention of prerequisites (e.g., needing ids from get_keywords), and no comparison to alternatives such as tag_keywords for organizing rather than removing.

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?

Goes well beyond the destructiveHint=true annotation by disclosing that deletion frees a plan slot, that shared terms survive deletion, and that dropping a single storefront preserves the rest of the market's corpora and build clocks. This is exactly the kind of side-effect and shared-resource context an agent needs before a destructive call.

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 the dual behavior, then consequences. Every sentence carries distinct information (mode selection, plan-slot effect, term sharing).

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?

An output schema exists, so return values need not be described. Combined with destructiveHint annotations, the description covers mode selection, side effects, shared-resource caveats, and plan implications – everything needed to invoke safely.

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 both params (baseline 3). The description adds meaning beyond the schema by explaining the storefront-level outcome of `store` (rest of market and build clocks untouched), which the schema does not fully spell out.

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 (delete a saved market or one storefront) and clearly distinguishes the two modes of operation. An agent can tell it apart from sibling tools like save_market, get_market, and list_markets 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?

Explicitly states when to pass `store` versus omitting it, and what each choice leaves untouched. It doesn't name sibling alternatives (e.g., save_market or remove_keywords) as routing options, so it stops short of full when/when-not guidance, but the operational 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?

Beyond the annotations (destructiveHint, openWorldHint), the description adds substantial operational context: text is published verbatim under the developer's name, removal is publicly visible once published, calls are batched up to ten items, per-item outcomes are returned, and a 'pending' result means Apple accepted but has not yet published.

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 action and scope, then moves to prerequisites, then to behavioural details. It is dense but every sentence carries weight; the only mild redundancy is restating the ten-item limit that the schema also documents.

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 destructive, multi-item mutation tool with strong annotations and a dedicated output schema, the description covers the remaining burden: approval prerequisites, dry_run semantics, partial-batch failure behaviour, and the pending outcome. An agent has everything needed to invoke it safely.

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

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

Schema description coverage is 100%, so the schema already documents dry_run, body, remove, review_id and the batching limit in detail. The description largely restates that information (up to ten items, dry_run validates without publishing) and adds little the schema does not already say, 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?

The opening sentence names a specific verb set (create, update, remove) and a specific resource (public App Store review responses) with scope (apps owned by the authenticated account). It is immediately distinguishable from the read-only sibling get_reviews, and the auth mechanism (connected App Store Connect API key) is stated.

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 clear prerequisites (write authorisation, eligible review ids, approval of exact text before submitting) and recommends dry_run for validation. It does not explicitly route the agent to a sibling for obtaining review ids, though the schema's review_id description points at get_reviews, which covers the gap somewhat.

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?

Goes well beyond the annotations: it discloses that an existing name replaces seed configuration and rebuilds storefronts (matching destructiveHint=true), that write authorisation is required, that corpus collection is queued as a background job which may still be pending, and what the response contains.

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

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

Front-loads the create/update purpose, then layers update semantics, side effects, auth and returns in dense but purposeful sentences with no filler. Slightly long, but every sentence carries 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?

Covers the mutation path, prerequisites (write auth), asynchronous side effects and caveats for a four-parameter tool with nested seeds. With an output schema present, its restatement of return fields is a bonus rather than a necessity, leaving nothing essential 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 name, query, seeds and countries are already fully documented in the schema; the description only restates the parameter list rather than adding format or constraint detail. Baseline 3 applies when the schema carries the semantics.

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

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

States a specific verb pair (create or update) and resource (saved market) plus the inputs it is built from, so an agent can distinguish it from siblings like get_market, edit_market_corpus and list_markets 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?

Clearly explains the create-vs-update branch: an existing name updates that market, adds storefronts, or replaces seed configuration and rebuilds. It gives strong context for the primary path but never names alternative tools (e.g. edit_market_corpus) or an explicit when-not-to-use condition.

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 say readOnlyHint=false and openWorldHint=true; the description supplies the real behavioral story the agent needs: a miss triggers an App Store fetch, persistence of a shared public app record, and an enrichment queue. That explains why a 'search' is not read-only, which the annotations alone leave opaque.

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?

Six sentences, front-loaded with purpose and searchable forms, then side effects, then routing. Every sentence carries information, though the closing note that no app_id lookup is needed slightly overlaps what the query parameter description already says.

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 an open-world, non-read-only lookup tool with 3 params, an output schema, and full schema coverage, the description covers the import side effects, region inference, and sibling routing. Nothing an agent needs to call 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 coverage is 100%, so the baseline is 3, but the description adds genuine meaning: the region is auto-detected from the query script (Cyrillic→ru, Chinese→China) and it warns that the guess reflects language, not market, so country should be passed explicitly when a market is named. It goes beyond restating 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?

Names a specific verb and resource ('Search for iOS apps') and spells out the accepted query forms: name, bundle ID, or App Store URL. It is clearly distinguishable from get_app, add_app, and other siblings by being the lookup/import entry point.

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 what this does NOT do ('does not add the app to your account or competitor watchlist') and routes the agent to the correct alternatives, add_competitors and add_app, noting they accept the same name or URL. This is exactly the when/when-not/alternatives guidance the dimension asks for.

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 openWorldHint=false, and the description is consistent with them while adding real behavioural context: a non-existent tag name is created, a keyword holds at most one tag so assignment replaces the prior one, the 500-id batch limit, and that untracked keywords are reported back rather than silently dropped. That is substantive disclosure beyond the structured fields.

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-loads the core action and the tag-vs-brand distinction before the detail, and every sentence carries operational information. It is somewhat long and partly restates the brand enum values already documented in the schema, which keeps it from a 5.

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?

An output schema exists so return values need not be explained, and the description still covers the app scoping, tag auto-creation, batch limit, replacement semantics, and error reporting. Nothing an agent needs to invoke this destructive mutation 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 coverage is 100% so the baseline is 3, but the description goes further by explaining cross-parameter semantics the schema does not: how tag and brand interact (brand alone leaves tags intact), and what omitting each field does (clear the tag / leave the brand decision alone). It adds meaning beyond the per-field descriptions.

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

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

States a specific verb+resource (bulk-tag tracked keywords) plus the secondary operations (clear tag, set brand), and explicitly separates itself from the read-side sibling by saying it is for organising after reading with get_keywords. An agent can distinguish it from add_keywords/remove_keywords 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?

Names the alternative workflow (get_keywords for reading, this tool for bulk organisation) and gives conditional usage modes: omit tag to clear, send brand without tag to change only the brand decision, override auto detection when it is wrong. The when-to-use context is explicit rather than inferred.

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