Applyra

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

Annotations already declare the safety profile (not read-only, not idempotent, open-world), and the description adds real value beyond them: it discloses the side effects (metadata fetched from the store, an initial visibility score computed, workspace linkage) and the plan app-cap cost. It stops short of addressing duplicate/repeat invocation behavior, 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 core action and followed by side effects and the quota constraint. No filler; every sentence carries information.

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

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

For a 4-required-param tool with 100% schema coverage, full annotations, and no output schema, the description covers purpose, side effects, and cost adequately. The main gap is duplicate-handling/error behavior, which is relevant because the tool is explicitly non-idempotent and open-world.

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 carries full parameter meaning, including the detailed lang/country and store enum semantics. The description only reiterates 'store bundle ID', adding no syntax or format detail beyond the schema. 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: 'Track a new mobile application by its store bundle ID.' It is clearly distinguishable from sibling add-tools that operate on different resources (add_competitor, add_note) and from read-side siblings like list_applications.

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

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

The description implies the intended scenario (bringing a new app under tracking) and notes the plan-cap implication, but it never states when to prefer this over related tools such as check_metadata or list_applications, nor what happens if the app is already tracked. Usage is inferable but not 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?

Annotations already declare it is a non-read-only, open-world, non-idempotent, non-destructive write. The description goes beyond that by disclosing the real side effects: store metadata is fetched and ranking entries are backfilled for every keyword tracked on the main app, which signals a potentially heavy write. It stops short of saying what happens on a duplicate add or on 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?

Two tight sentences: the action and its identifier come first, then the consequential side effects. No filler, nothing 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 mutation tool with no output schema and annotations covering the safety profile, the description supplies the essential behavioral picture (external fetch + ranking backfill). Minor gaps remain around duplicate handling, required preconditions, and error outcomes.

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 all five parameters are already documented in the schema, including the lang/country nuance and the store enum. The description only reiterates that the competitor is identified by store bundle ID, adding no format or validation detail beyond the schema.

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

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

Specific verb+resource with scope: it adds a competitor app to an existing main application and states the identifier (store bundle ID). It implicitly separates itself from add_application (main app vs competitor), but never names a sibling such as list_competitors or remove_competitor to sharpen 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?

The use case is implied (you add a competitor so its rankings get tracked), but there is no explicit when-to-use, no prerequisite stated (e.g., the main app must already exist/track keywords), and no guidance on checking for duplicates via list_competitors first.

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=false, idempotent=false, destructive=false, openWorld=false), and the description adds real behavioral context beyond them: the visible effect (a flag on visibility and keyword rank charts) and a hard validation rule ('a future day is refused'). What it omits is uniqueness/idempotency semantics, which matters for an idempotentHint=false 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-loads purpose, then behavior, then return shape, then the key constraint. Four compact sentences with no filler. Slightly dense but every sentence carries 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 specifying the exact return shape ({ app_id, note: { id, day, text, scope } }) plus the display side-effect and the day constraint. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents day, text, scope, and app_id in detail. The description largely echoes the schema's 'today or earlier' constraint rather than adding new meaning, so baseline 3 is appropriate.

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

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

States a specific verb+resource ('Add a note to an application's charts') and fleshes out what a note represents with concrete examples (campaign, metadata change, launch, price change). An agent can immediately distinguish this from siblings like update_note, list_notes, or compare_events.

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 usage context — notes annotate events for later before/after measurement — and points to the downstream sibling compare_events. However, it doesn't state when *not* to use it or contrast with update_note/delete_note beyond implication, so it stops short of full 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?

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 read-only/non-destructive, but the description adds substantial context: the causal caveat ('what followed... not what caused it'), metric direction, top-100 cap, unranked_days, pending_days, hidden_days, and the 'alongside' field. This is richer than the safety annotations and appropriately transparent.

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

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

Dense but front-loaded, opening with the core measurement purpose and then unpacking return semantics. Every sentence adds needed context for a complex comparison tool without an output schema, though the single-paragraph nested format is heavy.

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 complex, read-only tool with no output schema, the description supplies return structure, metric behavior, data limitations, and the causality caveat. Together with annotations and fully covered input schema, an agent has enough to invoke and interpret 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 all four parameters are documented structurally; the description largely duplicates those fields while clarifying window-day symmetry and keyword-rank direction. Baseline 3 is appropriate because the schema already does the heavy lifting, with only marginal added meaning.

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

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

States a specific verb ('Measure what followed each event') and resource (application events, user notes, app updates), and distinguishes the default visibility-score metric from the keyword-rank alternative via keyword_id. An agent can tell this apart from general history tools like get_app_score_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?

Implies the use case—comparing before/after windows around application events over the last year—but does not state when to choose this over history-specific siblings such as get_app_score_history or get_keyword_rank_history. It gives clear context but lacks explicit alternatives or exclusions.

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

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

Annotations only declare destructive/idempotent/not-read-only; the description goes further by disclosing a non-obvious side effect (subsequent notes are renumbered) and the exact return payload { id, deleted: true }, which matters because no output schema exists.

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 short sentences, front-loaded with the action, then the input source, then the side effect and return value. Every sentence carries information 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?

For a single-parameter delete with no output schema, the description supplies the missing return shape and the cascade side effect, so an agent can call it and interpret the result correctly with nothing material left out.

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 parameter's description already says it is the numeric note ID from list_notes, so the description's ID guidance is largely redundant. Baseline 3 for a fully documented single-parameter 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 ('Delete a note') plus the scope ('from an application's charts'), which cleanly separates it from add_note, update_note and list_notes 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 gives the prerequisite workflow step ('Pass the note id from list_notes'), which tells the agent where the required identifier comes from. It does not name exclusions or alternatives (e.g. when to update rather than delete), 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?

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 only declare it a safe, closed-world read; the description goes far beyond by disclosing that score is null on days without a snapshot, that dates are swapped when reversed and clamped when in the future, and that the payload includes an events block explaining moves. 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?

Front-loaded with the answer, then return shape, then routing, then edge cases — a logical order with no filler sentences. It is dense and long, but nearly every clause carries a constraint or a return-value fact an agent needs, so the length is largely earned.

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

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

There is no output schema, so the description must describe the return value, and it does: app_id, app_title, resolved from/to, history[] of {date, score}, and events {notes, app_updates, store_updates}. Combined with the plan-limit and date-normalization rules, nothing essential for a correct first call 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, and the description still adds real meaning: app_id is the numeric internal ID from list_applications, not the store bundle ID, and from/to are subject to plan-window shortening, swapping, and clamping. It stops short of any format detail for the date strings 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+resource and scope: daily visibility score history for one application. It also defines what the score means (0-100 discoverability across a stable keyword set) and explicitly distinguishes itself from get_keyword_rank_history and compare_events, so an agent can place it among the siblings without opening a schema.

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

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

Explicit routing: 'To measure what followed each event, use compare_events' and 'For one keyword rank over time, use get_keyword_rank_history.' It also covers the default window (last 30 days, shortened by the plan's history window), the failure condition (an explicit start older than the plan returns PLAN_LIMIT), and the 400-day hard cap.

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/destructiveHint/openWorldHint, so the safety profile is covered. The description adds substantive behavior beyond that: the result is stored and the audit refreshes automatically, so reads are sub-millisecond and non-rate-limited; report is null (not zero) for apps the audit never reached; targeting.assessable is false when no searched term exists.

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 reasonably front-loaded — purpose first, then return shape, then axes/tier semantics, then sibling routing at the end. It is long and occasionally repetitive (the tier/verdict point is restated), but virtually every sentence is substantive, which matters because there is no output schema to carry the return-shape burden.

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: it enumerates every reported structure (global, three axes, tier, fields[], phrases[], targeting{}, flags[], timeline[]) and explains sentinel states (empty/missing/truncated/unsearched/assessable). An agent can interpret the payload correctly without further documentation.

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

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

Schema coverage is 100%, so both parameters are already documented in-schema, including the detailed include_words status vocabulary. The description adds only marginal parameter value (the 'attributable score' framing around app_id and the 'off by default, rarely needed' framing of include_words). 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 first sentence states a specific verb and resource and draws a sharp contrast: 'how well its listing is WRITTEN, as opposed to how it currently ranks.' It also implicitly separates itself from the two sibling tools it names later, so an agent can distinguish it from get_app_score_history and simulate_metadata 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 routes the agent: 'For visibility over time instead, use get_app_score_history; to score a listing that does not exist yet, use simulate_metadata.' It also gives a use-freely signal ('call it as often as you need') and warns that report=null is not a zero score, removing the main misinterpretation risk.

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 it as a non-destructive read; the description goes well beyond that, disclosing default window (30 days capped by plan history), the PLAN_LIMIT failure on older explicit starts, the 400-day hard maximum, date swapping/clamping behavior, and rank=null vs omitted-day semantics. 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?

Front-loads the return shape, then behavior, then parameters, then the alternative — a sensible order with no filler sentences. It is a dense single paragraph with some long chained clauses, which makes it harder to scan than it could be, but every sentence carries 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 fully documents the return payload (keyword, store, country, lang, resolved dates, apps[] with history and events). For a read-only tool with four simple params, nothing an agent needs in order 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 real meaning on top: where keyword_id comes from, that app_id narrows rather than filters by owner, and non-obvious from/to dynamics (reversed dates swapped, future clamped, plan-window truncation, 400-day cap) that the terse schema strings omit.

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 ('Get the daily rank history of one tracked keyword') and immediately scopes it to one keyword with one series per tracking app. It is clearly distinguished from the sibling get_app_score_history, which is named as the tool for whole-app visibility.

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: 'Pass keyword_id from list_keywords, and app_id to narrow the output to one app,' and 'For the visibility of a whole app rather than one keyword, use get_app_score_history.' The selection condition against the closest alternative is stated outright.

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?

Annotations declare readOnlyHint=false and openWorldHint=true, and the description adds the key behavioral detail explaining why it isn't a pure read: it consumes an inspection quota, except for already-tracked keywords. That quota rule is genuine context beyond the annotations. It does not cover latency, caching, or error behavior, so not 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?

Front-loaded with the purpose, followed by a dense but useful enumeration of return fields and the quota rule. Every clause carries information, though the long return-value list is list-heavy; it earns its place only because no output schema exists.

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 burden of describing returns and does so thoroughly (difficulty_score, traffic_score, KEI with level, top-20 ranking apps with fields, related suggestions, tracked status). Combined with the quota behavior and full parameter documentation, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% and the lang parameter in particular is richly documented (market vs. language-region distinction). The description adds no parameter-level 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?

States a specific verb and resource ('Deep-analyze any keyword') with an explicit scope qualifier ('even ones you don't track'), so the agent knows this works on untracked keywords. It does not name any sibling (e.g. list_keyword_inspections or run_niche_analysis) to differentiate, so it stops 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?

Usage is implied by the scope note ('any keyword, even ones you don't track') and the quota caveat, which tells the agent the operation is worth running on tracked keywords. However, there is no explicit when-to-use/when-not guidance or reference to alternative tools like run_autocomplete or run_niche_analysis, leaving the routing decision 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 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/openWorldHint/destructiveHint, so the safety profile is covered. The description goes beyond them by disclosing the return shape (app_id and notes[]), ordering ('oldest first'), and semantics of the tricky fields (number, scope), which is valuable given no output schema exists.

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 format, then routing. The field-by-field explanation of number and scope is slightly verbose but each sentence carries information an agent needs; overall it is efficient rather than 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?

For a read-only single-parameter tool with no output schema, the description supplies the return structure, ordering, field meaning, ID provenance, and the natural next step (compare_events). Nothing needed to invoke or interpret it 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?

With 100% schema coverage on a single parameter, the schema already documents app_id fully. The description's 'Pass the numeric internal ID from list_applications' reinforces source/format but adds little beyond the schema's own 'numeric, from list_applications results' wording, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('List the notes on an application's charts') and immediately grounds it with concrete examples ('launched a Reddit giveaway', 'changed keywords'). It distinguishes itself from the write siblings by noting it is read-only and routes to compare_events as the follow-on 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?

Gives clear usage context ('Pass the numeric internal ID from list_applications') and names an alternative ('To see what followed each note, use compare_events'). It does not state when *not* to use this tool, so it falls short of 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 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 annotations already declare non-read-only, non-idempotent, open-world behavior; the description goes further by disclosing the cost profile ("Consumes one autocomplete query and one API request"), which is the key behavioral fact an agent needs before calling. It does not, however, describe the response shape.

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 scoped constraints; the cost sentence earns its place. The middle "useful to discover" sentence is somewhat expendable but not wasteful.

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 does not explain what suggestions come back or any result limits, which is a minor gap for a simple fetch tool. Purpose, cost, and constraints are otherwise complete, and readOnlyHint=false is consistent with the stated quota consumption.

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 four parameters, including the 1-60 prefix limit and the BCP-47 language detail. The description's only added parameter detail is the prefix length range, which is 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 (fetch autocomplete suggestions) plus the two target stores, and scopes it to a prefix. An agent can distinguish it from list_autocomplete_history (viewing past runs) 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?

Names a use case ("discover what users are searching for that starts with a given seed") but offers no when-not guidance and never mentions the obvious alternative, list_autocomplete_history, for retrieving prior results. Usage is implied rather than specified.

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

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

Annotations declare readOnly=false, openWorld=true, idempotent=false, destructive=false, but the description adds meaningful behavioral context the annotations cannot convey: cache hits under 7 days return instantly without consuming quota, and fresh analyses take minutes. This quota/latency disclosure is exactly the kind of added value that justifies a high score; error/auth behavior is not covered, so it stops short of 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?

Four tight sentences, front-loaded with what the tool does, then outputs, then cache/quota, then latency. No filler; each 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?

With no output schema, the description correctly enumerates the return shape (clusters, keywords, opportunity scores, intent type, app concept suggestion) and covers caching and latency. It stops short of noting whether analyses persist or how results are retrieved later, which list_niche_analyses implies. Largely complete for a 4-param pipeline tool.

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

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

Schema description coverage is 100% and includes careful guidance (e.g., the lang/country distinction, store enum values), so the schema does the heavy lifting. The description only implies the 'topic' input and adds no syntax or format detail beyond the schema, 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 states a specific verb and resource and unpacks the full pipeline: discovers keywords, clusters into sub-niches, scores each cluster's opportunity. This distinguishes it from sibling tools like run_autocomplete or list_niche_analyses, which do not perform clustering/scoring. An agent can tell what it produces 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 pipeline description, but there is no explicit when-to-use guidance nor any named alternative or exclusion (e.g., versus run_autocomplete for keyword discovery). The cache/quota note informs expectations rather than routing. Adequate but with a clear gap in directive 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, 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?

Goes well beyond the annotations: discloses latency ('expect a few seconds per call'), cache-warming semantics via words_fetched, non-fatal request problems surfaced in notes[], per-axis null delta semantics, and the warning that lost_phrases[] carries signal the score alone does not. Annotations (readOnlyHint=false, idempotent=false) are consistent with the saved-run behavior it describes.

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 action and the mode split, and nearly every sentence carries information (comparability warning, latency, cache effect). It is a single dense block, though, and the long return-value enumeration would scan better as separate sections.

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 takes on the return contract itself and discharges it fully: app, aso_health axes and tier, delta null semantics, flags, lost_phrases with their caveat, the saved run, notes, and the words_probed/words_fetched meaning. Nothing an agent needs to call correctly or 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 schema carries the field documentation, but the description still adds real semantics: app_id inherits the live listing so { app_id, title } is complete, store/country/lang are only required without it, context keys merge over the app's real values, and kw_field is ignored on Google Play. It adds less about subtitle/description 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 and resource ('Score a listing that does not exist yet') and immediately differentiates itself from the sibling audit engine and from check_metadata. The two-mode framing (with/without app_id) makes it unmistakable which tool this is.

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

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

Explicitly says when to use it ('is my draft better than my listing'), the required parameters per mode, the prerequisite (check_metadata first, don't poll), and names the read-back alternatives (get_metadata_simulation, list_metadata_simulations). It also states when-not: without app_id the global score is not comparable and must not be presented as one.

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 valuable behavioral context by describing the returned data, including daily rank movement, snapshot date, and the specific fields (e.g., delta vs. yesterday, is_new), which matters because no output schema is provided.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by useful return-field and parameter details. The long parenthetical list of returned fields is slightly dense, but it earns its place because there is no output schema to document the response.

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 lack of an output schema, the description helpfully enumerates the returned fields and explains the category and collection semantics. It does not mention the limit parameter or how to discover valid category values (e.g., via list_top_chart_categories), but those gaps are minor because the schema covers parameter details and the core return behavior is described.

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 five parameters. The description largely repeats the schema's parameter descriptions, including the same examples (iTunes genre id '6014', Google Play category 'GAME') and defaults (OVERALL, free), adding no meaningful semantic detail beyond what the structured schema provides.

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

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

The description states a specific verb and resource: retrieving a store top-chart ranking for a given country, category, and collection. It names the two stores (App Store or Google Play) and the chart types, which distinguishes it from sibling tools like list_top_chart_categories and the keyword-rank-history 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?

The description implies the tool's use case (fetching a top-chart ranking) and provides parameter defaults, but it does not explicitly state when to choose this tool over alternatives or when not to use it. No sibling tool is named as an alternative, so the guidance remains implicit.

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=false, idempotentHint=false, destructiveHint=false), and the description adds genuinely useful behavior beyond them: a hard batch cap of 20, an immediate ranking fetch triggered per keyword, partial-failure semantics ('per-keyword error in `results`'), and silent reactivation of removed keywords. It stops short of mentioning credit/quota cost or rate limits for the immediate fetch.

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 capability and batching limit, then side effects, then the app_id provenance hint. No filler or redundancy.

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

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

For a 5-required-parameter write tool with no output schema, the description supplies the essentials: batch cap, immediate-fetch side effect, per-keyword error reporting in `results`, and reactivation behavior. It references the `results` field but does not describe the overall response shape, a minor gap given 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%, so all five parameters (including the lang/store/country nuances) are already documented in the schema; the baseline is 3. The description's only added hint, 'Use app_id from list_applications results', restates what the app_id schema description already says, and the 20-keyword limit is likewise already in the array constraints.

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

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

The description gives a specific verb (Track), resource (keywords), scope (up to 20 new keywords for one application in a single call), making it immediately distinguishable from siblings like untrack_keyword, list_keywords, and inspect_keyword. An agent can tell what the tool does 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 states the context for invocation ('Use app_id from list_applications results') and handles edge cases — already-tracked keywords return a per-keyword error, previously removed keywords are reactivated. It does not explicitly name untrack_keyword as the inverse or spell out when-not-to-use, but the intended usage 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 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.

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

Goes beyond the annotations (which already flag destructiveHint/idempotentHint) by disclosing the non-obvious side effect that moving a note to another day can renumber other notes, and by spelling out the return shape since no output schema exists. It still says nothing about permissions or failure modes.

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 compact sentences plus a return shape, with the highest-value information (partial update, id source, renumbering side effect) front-loaded and 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 3-parameter mutation with no output schema, the description covers partial-update semantics, the id prerequisite, the cross-note side effect, and the response shape — everything an agent needs 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 coverage is 100%, so the baseline is 3, but the description adds real meaning the schema lacks: omitted fields are preserved rather than cleared, and note_id must come from list_notes. Day format and length limits stay in the schema, so it does not need to repeat them.

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 (Change) plus the exact fields it can change (text, the day, or both) on the note resource, and the id source, so it is instantly distinguishable from add_note, delete_note and list_notes in the sibling set.

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

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

Gives clear operating context: pass note_id from list_notes, and a field left out keeps its existing value (patch semantics). It does not, however, state when to prefer deletion or how the call behaves if the note does not exist, so it is clear context without explicit exclusions.

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