ExtensionDash

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

With no annotations, the description carries the full behavioral burden and does so: it discloses that the promotion triggers a store fetch (description, install count, rating, languages), that ranking history is backfilled from existing searches, that the response omits the description, the pending->scraped async status flow via list_competitors, the 20-per-store cap counted separately per store, and the account requirement.

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, then layers workflow, behavior, limits, and auth. It is relatively long, and the ranking-history paragraph borders on promotional, but nearly every sentence delivers operative detail 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?

No output schema or annotations exist, so the description must cover everything, and it does: return behavior, async status checking, per-store limits, and account prerequisites. An agent has all it needs to call this correctly and handle the result.

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

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

Schema coverage is 67%, and the description adds meaning by tying store/external_id to search_store's return values ('exactly as search_store returns it') and extension_id to list_extensions. This complements the schema rather than restating it, though it does not add format detail beyond the schema's own descriptions.

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

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

States a specific verb+resource ('Start tracking a competitor') and clarifies scope ('for an extension') against the sibling add_keyword by naming the tracked entity. It does not explicitly contrast itself with siblings like add_keyword or search_store, but the purpose is unambiguous.

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

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

Gives explicit when-to-use context: 'Takes the same store and external_id that search_store returns, so a result you just saw on a SERP can be promoted.' It also names the fallback tools (find_listing, get_store_listing) for users without an ExtensionDash account, covering when-not-to-use.

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?

No annotations are provided, so the description carries the full burden — and it does: it discloses the async nature (no position on return), the status lifecycle, per-store/per-language tracking semantics, the beta limit of 15 keywords counted per language, the limit-error behavior plus the remove_keyword remedy, and the account requirement with a signup path.

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 paragraphs, front-loaded with purpose and mechanism, then polling guidance, then locale semantics, then limits/auth. Dense and largely earning its place, though the locale paragraph and the limit paragraph overlap on the 'per language' point, allowing minor trimming.

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

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

For an async mutation tool with no annotations and no output schema, the description covers everything an agent needs: auth prerequisite, async result handling, error paths, limits, and the follow-up calls to verify outcome. Nothing material 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. The description goes beyond the schema by tying locale to limit counting ('ad blocker' in en and de is two of them) and by explaining that a term is tracked independently per store language, giving the locale parameter operational 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+resource ('Start tracking a search term for an extension') and immediately explains the mechanism: one term per store, with a rank fetch enqueued per store. This is clearly distinct from siblings like add_competitor, remove_keyword, 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 routes the agent: poll list_keywords until status flips pending→scanned, or watch list_scrape_runs for failed fetches, and it names find_listing/get_store_listing as the fallback for users without an ExtensionDash account. It even states when-not (unauthenticated users cannot use it).

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

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

No annotations, so the description carries the full burden and does so: it states no fetch occurs, no egress budget is spent, the call is logged and rate-limited, long names are refused rather than trimmed, and it deeply qualifies the `cached` flag's meaning for guests vs. signed-in users including the 'pending'/stale/failure possibilities.

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 name-vs-id trigger are front-loaded, and each paragraph covers a distinct concern (matching tolerance, scope vs. search_store, cost/logging, `cached` semantics, locale, ambiguity, refusal). It is long and somewhat essayistic, but almost every sentence carries non-redundant operational detail rather than padding.

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

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

With no output schema and no annotations, the description still tells the agent what comes back (`cached`, `publisher`, ranked matches) and how to interpret each, plus the failure and refusal modes. Nothing needed to invoke or interpret the 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, but the description adds real semantics beyond the schema: it explains that `cached` answers for exactly one locale because a Chrome listing in German needs two fetches, and warns to pass the locale you intend to read in — meaning the schema text alone ('Does not change which names match') doesn't convey.

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 precise verb+resource+transformation: 'Turn an extension's NAME into the store id every other tool asks for.' It explicitly distinguishes itself from search_store ('It is not a store search') and positions itself relative to get_store_listing, so an agent can route correctly without opening the schema.

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

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

Gives an explicit trigger ('Start here whenever you were handed a name rather than an id or a store URL'), names the alternatives and when to prefer them ('Use search_store if what you have is really a search phrase'), and prescribes a fallback when nothing matches (ask for the URL/id and pass to get_store_listing).

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

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

With no annotations, the description carries the full burden and largely meets it: it discloses that the data is 'the tracked view, built from what we have recorded' (i.e., recorded snapshot data, not a live fetch), states the account requirement, and names the exact recovery path (signup URL, reconnect via the URL on /profile). It does not explicitly state that the call is non-mutating or describe freshness/pagination limits, leaving a small gap.

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

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

Four short paragraphs, each with a distinct job: what it returns, return shape, alternatives for time series, and access/fallback. The purpose is front-loaded in the first clause. The account/signup paragraph is the most verbose part but is genuinely load-bearing for a gated tool.

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 must explain the payload, and it does: per-store-listing latest numbers, tracked keywords with positions, and a 'locales' field with per-language keyword counts. Combined with the access-path detail, an agent has enough to invoke it correctly; only return-format specifics (field names, pagination) are 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 the single parameter is documented in the schema as 'From list_extensions.' The description adds no syntax or provenance detail for extension_id, but it does explain the returned 'locales' structure, which is output rather than parameter guidance. Baseline 3 when the schema does the work.

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

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

States a specific verb+resource ('One extension in full') and enumerates contents: every store listing's latest numbers, tracked keywords, and their current positions. It explicitly contrasts itself with get_store_listing ('the tracked view ... For an extension this account does not track ... use get_store_listing instead'), so an agent can distinguish it from siblings without opening a schema.

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

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

Gives explicit when/when-not routing: use get_metrics_history or get_keyword_ranks for movement over time, and get_store_listing for untracked extensions or listings in other languages. It also states access prerequisites (ExtensionDash account) and names the fallback tools that still work without 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?

With no annotations, the description carries the full burden and does well: it explains that each point carries its scan depth, that a null position means the extension was not found at that depth, and that one term tracked in multiple store languages yields one series per language. It discloses the account prerequisite. It does not cover rate limits, pagination, or ordering of returned series.

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 statement, then two short paragraphs of semantics and one of prerequisites. Every sentence carries information, though the depth explanation is a touch discursive for a definition.

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 convey return shape; it does so by describing series granularity, the depth field, and null-position semantics. Combined with an 80%-covered five-parameter schema, an agent has enough to call it correctly, though ordering and volume of results remain unspecified.

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 80%, so the baseline is 3, and the description adds genuine meaning on top: the depth/pool-size framing justifies the ranking values, and 'one series per term per store' clarifies how term, store, and locale combine into output series. It does not add format or canonicalisation details beyond what the locale schema entry already provides.

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

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

States a specific resource and scope: 'Daily search position history for an extension's tracked keywords, one series per term per store.' An agent can tell this is a historical ranking-series tool, not a SERP fetch or a metrics tool. It does not explicitly differentiate itself from siblings like get_keyword_serp or get_metrics_history, 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?

Gives a real conditional: it needs an ExtensionDash account, and without one the agent should fall back to find_listing or get_store_listing for current store pages. That is explicit when/when-not routing. It never states when to prefer this over get_keyword_serp or get_metrics_history, so it is not a full 5.

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

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

With no annotations, the description carries the full burden and does well: it discloses that data is read from recorded history with 'no fetch, no waiting, no egress spent', that rows carry mine/competitor flags, and that positions must be read alongside depth_scanned. It does not state pagination, result-size limits, or what happens when a term has no recorded history — a meaningful gap for a history-backed read.

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 in the first sentence, then routing, then capability, then the auth note — a sensible order. Slightly literary phrasing ('who was on it, in what order, and which way each of them moved') costs a little density but every section still conveys usable 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?

No output schema and no annotations means the description must supply everything, and it covers data source, freshness semantics, auth requirements, fallback tools, and the caveat that positions are only meaningful with depth_scanned. An agent has what it needs to call this correctly and interpret the result.

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

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

Schema coverage is already 80%, so the schema documents term, store, locale, window and extension_id without help. The description adds context about what rows contain (flags, depth_scanned) but does not explain the 'window' boolean or locale behavior beyond what the schema states. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('the search page for one of an extension's tracked keywords, as this account last recorded it') and enumerates what the result contains (who, order, movement over the past week). It explicitly distinguishes itself from the sibling search_store, so an agent can route 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?

Directly names the alternative and the selecting condition: 'Use search_store instead when you need what the store is showing right now; use this when you want movement.' It also gives fallbacks for unauthenticated callers (find_listing, get_store_listing) and states the account prerequisite.

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 annotations, the description carries the full burden and delivers: empty map means no measurement rather than zero, rounding caveat tied to users_rounded_in_range, competitor capture cadence ('every few days rather than daily, and not on a fixed schedule'), the (store, external_id) join key with name explicitly demoted to a label, and the hard-fail semantics of an unlisted pair. Auth requirements and a signup path are also disclosed.

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

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

The opening sentence front-loads the core purpose and return shape before drilling into caveats, and almost every sentence carries non-redundant behavioral information. It is dense to the point of being long, but there is little filler to cut.

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?

Despite having no output schema, the description defines the return structure (maps of ISO date to value, empty-map semantics, rounding flag) and the lookup-time caveats needed to compare a competitor against this extension's own listings correctly. Nothing essential for a correct 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, but the description adds genuine meaning beyond the schema: that competitors implies include_competitors, that an off-roster pair aborts the whole call rather than being dropped, and that store filters both listings and competitors simultaneously. It stops short of extra syntax or default guidance the schema does not already contain.

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

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

States a precise verb+resource (historical metrics for a single extension) and enumerates exactly what is returned: user count, rating, ratings count, each as an ISO-date-keyed map. It also disambiguates the two data sources ('listings' = this extension's store listings, 'competitors' = its roster from list_competitors), so an agent can separate it from list_competitors or get_extension without opening a schema.

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

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

Explicitly documents the include_competitors / competitors dependency ('competitors ... implies include_competitors; a pair not on the roster fails the whole call'), which is non-obvious routing behavior. It also names the alternative for unauthenticated callers (find_listing and get_store_listing still read current store pages) and the exact prerequisite (an ExtensionDash account plus reconnection via the /profile URL).

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 annotations, the description carries the full burden and delivers: HTML/entity/redirector stripping for AMO vs pass-through for Chrome, the Chrome-vs-Firefox locale rendering difference ('real, not a bug'), the copy-timeline side effect of signed-in reads, guest reads writing no research state, day-long caching with 'pending' cold-start, and 'sign_in_required' for uncached guest reads. This is exactly the behavioral depth an agent needs.

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 and function, then layers behavior in short paragraphs. Mostly tight, but 'tracked by any account, not just yours' is repeated (once in include_copy_history's schema text), and the block is longer than strictly necessary, costing a perfect score.

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, yet the description enumerates the returned fields (description, supported languages, category, install count, rating, version) and covers all three terminal states (pending, ready, sign_in_required) plus cache-age behavior. An agent has everything needed to poll and interpret results.

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 80%, so the baseline is 3; the description adds value by explaining that locale changes which store language is used and how the store renders languages, and by describing include_copy_history's scope (only stored listings, signed in only). It doesn't restate external_id formats or max_age beyond the schema, but the added locale/copy-history context lifts it above 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 (return one extension's store page) and resource, with the key scoping fact up front: 'any extension, tracked by this account or not.' This immediately distinguishes it from get_extension, which is for tracked extensions.

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 itself as 'the competitor-research and copy-review tool' and names the alternative and its condition: 'Use get_extension instead ... when you want its recorded numbers over time.' Both when-to-use and when-to-use-something-else are covered.

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 annotations, the description carries the full burden and does so: it discloses that data is read from already-recorded positions (no fetch, no waiting), that promoted competitors' positions persist even when they drop out of results, and that rows carry evidence (term count, average position, first seen). It also states the account prerequisite and a recovery path.

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 definition and two-set distinction, and every sentence carries information. It runs slightly long, and the signup/reconnect paragraph is operationally useful but dilutes the core content; still well above the minimum-viable bar.

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 must convey return shape and it does: the two sets, the fields recorded for competitors, and the evidence attached to each row. Auth requirements and fallback tools are also covered, leaving nothing material for correct invocation missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it explains the semantic difference between the two result sets and the exact effect of include_observed (adds unpromoted 'candidates' ranked by how often they beat you). Only extension_id's rarity/format beyond 'From list_extensions' is not elaborated.

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 resource (competitors) and scope (measured across every keyword the extension tracks), and immediately frames the payoff ('the tool for deciding who is worth promoting'). An agent can distinguish it from add_competitor/remove_competitor, which mutate the roster this tool reads.

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 names the decision context it serves and the conditional that selects the second result set ('returned only with include_observed'). It also routes the agent to find_listing and get_store_listing for users without an account, which is exactly the alternative-selection guidance expected.

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?

No annotations exist, so the description carries the full burden, and it does well: it discloses the account requirement, what still works unauthenticated (find_listing/get_store_listing read any store page), and a data caveat (the store may round the user count). It stops short of describing pagination, result caps, or rate limits for large portfolios.

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: the core output and the 'start here' routing appear first, with the auth/signup logistics last. The final paragraph is dense and slightly repetitive about the signup URL, but every sentence carries routing or auth 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 and no parameters, the description supplies the return-field inventory itself, plus the auth story and the fallback chain into sibling tools. Nothing an agent needs to select or call this tool is missing.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to add beyond confirming that the listing is implicitly scoped to 'this token's owner', which it does.

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 every extension the token owner tracks) and enumerates the payload fields: user count with rounding flag, 7-day change, rating, ratings count, category rank. An agent can distinguish it from list_competitors/list_keywords/list_scrape_runs purely from this sentence.

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 'Start here when this connection has an account' and explains why: every tracking tool takes an extension_id from this list. It also names the alternative path — find_listing then get_store_listing — and states the condition (no account) 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?

With no annotations, the description carries the full burden and does so: it defines pending vs scanned, explains that a scanned row with null position is a real negative observation, that a pending row may still carry a stale position (captured_on), and why search_volume is null. It also states the account requirement and what still works without one.

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 in sentence one, and with no output schema each subsequent block (status, locale, locales, search_volume, auth) explains a returned field that would otherwise be opaque. It is dense and paragraph-heavy rather than bulleted, but almost 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 2-param tool with no output schema and no annotations, the description covers the return shape field-by-field, the auth precondition, the polling condition, and the negative-observation case. Nothing an agent needs to interpret or call the tool correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents both params and a baseline of 3 would be acceptable. The description adds genuine meaning: locale is the store language searched under, the same term ranks differently under hl=de vs hl=en, and the locale argument narrowing rows does not change what locales reports.

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

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

The opening line gives a specific resource and scope: every tracked search term for one extension, one row per term per store. That is precise enough to separate it from siblings like get_keyword_ranks or get_keyword_serp, which return result data rather than the tracked-term inventory.

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 actionable usage direction: poll until status reads 'scanned' to trust the position, and start from the locales field to work a language at a time. It also names an explicit fallback path (find_listing, get_store_listing) when no account is present. It does not, however, contrast this tool against get_keyword_ranks/get_keyword_serp for result-level questions.

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 annotations, the description carries the full burden and does reasonably well: it declares the auth requirement (ExtensionDash account), the failure-reporting behavior (failed fetch shows as failure rather than a missing position), and result ordering. It omits pagination/limits behavior and any rate or cost details, keeping it short of a 5.

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

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

Front-loaded with the core behavior and consumed efficiently, though the signup/reconnect paragraph is fairly verbose for a definition. Every section is relevant, but the auth-recovery instructions could be tighter.

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 or annotations exist, so the description is the main source of context, and it covers auth, ordering, content, and failure semantics for a read-only listing tool. Remaining gaps (pagination, empty-result behavior) are minor.

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 67% and the schema already documents limit defaults, the status enum, and extension_id. The description adds only the loose implication of 'your own extensions' scoping and does not clarify status/limit semantics, so it roughly matches the structured 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+resource (recent scrape attempts against your extensions) plus ordering ('newest first') and returned content ('outcome and any error'). It also scopes the resource further by saying it covers both listing fetches and rank fetches, which separates it from siblings like get_keyword_ranks.

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 concrete usage moment ('Use this after add_keyword to watch the rank fetch') and names alternatives for the unauthenticated case (find_listing, get_store_listing). It does not state an explicit when-not-to-use, but the alternative routing is clear enough for selection.

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 annotations, the description carries the full burden and does so well: it discloses that store fetches stop, that history is retained, that re-adding restores charts, that positions keep being observed via existing searches, and that an account is required. These are non-obvious side effects an agent could not infer from the name or schema.

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

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

Front-loads the core action in the first sentence, then adds behavioral and auth context. Every sentence carries information, though the auth paragraph is slightly verbose for a three-parameter operation.

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 annotations and no output schema, the description covers side effects and auth prerequisites thoroughly. It omits error/edge-case behavior such as removing a competitor that isn't tracked, which is the remaining gap.

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

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

Schema coverage is 67% with two of three parameters documented in-schema ('From list_competitors', 'From list_extensions') and store constrained by an enum. The description adds no parameter-level detail (e.g. what happens if external_id is unknown), so the baseline 3 is appropriate given the schema does most of the work.

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

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

States a specific verb and resource ('Stop tracking a competitor for an extension'), clearly distinguishing it from add_competitor and remove_keyword. The scope is unambiguous and an agent can select it without opening the schema.

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

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

Provides a clear usage condition (needs an ExtensionDash account) and names alternatives (find_listing, get_store_listing) for unauthenticated callers, with a signup path. It doesn't explicitly characterize when removal is appropriate versus just leaving tracking alone, which keeps it just below 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?

With no annotations, the description carries the full burden and does so richly: positions already recorded are kept, shared store listings cause the removal to propagate to every connected extension, and the operation is per-locale rather than per-term. It also discloses the account prerequisite and the unauthenticated fallback tools.

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, then the consequence, then the sharing semantics, then locale details. Slightly long in the account/signup paragraph, which drifts toward onboarding copy rather than tool semantics, but overall every section is substantive.

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 annotations and no output schema, the description covers the crucial unknowns: what is and isn't destroyed (positions kept, tracking stopped), propagation via shared listings, and auth requirements. Nothing an agent needs to invoke it safely 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 beyond the schema by explaining that a term is tracked per store language and that en/de are independent keywords with their own positions. The 'As reported by list_keywords' contract for term is reinforced by the prose.

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

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

Opens with a specific verb+resource+scope: 'Stop tracking a search term for an extension, across every store it was tracked in.' This clearly distinguishes it from add_keyword and list_keywords, which are named or implied in the siblings list.

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

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

Tells the agent when to use it (to stop tracking) and points to list_keywords to discover the locales an extension tracks. Lacks an explicit when-not-to-use or a direct contrast with the alternative (add_keyword), but context is clear.

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

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

No annotations are provided, so the burden is on the description—and it delivers real behavioral disclosures: results are cached for a day, fetched in the background, a cold search returns status 'pending' requiring repeated polling, signed-out returns 'sign_in_required', and rows are deliberately thin. It doesn't describe auth requirements in detail (what constitutes 'signed in') or output field structure, but the status-code and caching contract is the critical part and is stated.

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 content is front-loaded with the SERP framing, but the prose is somewhat rambling—several sentences about competitor_of, locale, caching, and sign-in state intermix. Most of it earns its place, but the 'Signed in, any result that IS one of yours carries its extension_id' and 'competitor_of' passages could be tightened. It's longer than needed for the core contract.

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 6-param search tool with no output schema, the description covers the important unknowns: caching behavior, async status handling, auth-dependent behavior, and what the rows contain (thin, with extension_id/competitor_of markers). It doesn't fully specify what the SERP response shape looks like, but it names the status states and the lightweight row contract, which is sufficient to call 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 83%, so the schema already documents most parameters (term squishing, max_age caching semantics, defaults). The description adds real meaning for 'locale' by explaining it's a 'real ranking axis, not a translation of the page' with concrete hl=de/hl=en examples—value beyond the schema. 'term' and 'page' get little added context, but the locale explanation compensates.

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

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

The description names a specific verb and resource ('Search a store... read the results') and immediately frames it as 'how you see a real SERP: who ranks for a term, in what order, with the titles and taglines they rank with.' It distinguishes itself from the sibling 'get_keyword_serp' by scoping to a store-level SERP with competitor visibility, and it explicitly routes page-reading to 'get_store_listing'.

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

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

It tells you when to use this versus alternatives: 'To rank rivals rather than read one page, use list_competitors with include_observed', and it points to 'get_store_listing' for richer per-page data. It also covers the signed-out branch ('Without an account this answers from cache only'). No explicit when-not-to-use clause, but the routing guidance is clear and actionable.

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