ExtensionDash

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

Beyond the annotations (write, idempotent, destructive, openWorld), the description discloses the async lifecycle (no description on return; poll until status changes), the quota ceilings (5 Free / 20 Premium, counted per store), the auth requirement with concrete login commands, and exactly what data starts being recorded plus retained rank history. This adds substantial context the structured fields do not 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?

Purpose and the key input relationship are front-loaded, and quota/auth facts are separated into their own paragraphs. The rank-history passage ('Where it ranks has been recorded all along... rather than starting from zero') is somewhat wordy for the value it adds, keeping it from a 5.

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

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

With no output schema, the description correctly explains return behavior (description not available yet, poll list_competitors), plus quota, per-store counting, and auth needs. Nothing an agent needs to invoke and then correctly wait on this tool is missing.

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

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

Schema coverage is 67%, and the description fills the remaining gap by tying external_id to a search_catalog row's id and noting it can be promoted without a separate lookup; store's enum and extension_id's source are already in the schema. It adds genuine meaning but doesn't document every parameter edge (e.g., AMO slug vs Chrome id formatting is only 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?

The opening sentence states a specific verb and resource ('Start tracking a competitor for an extension') and the surroundings make it clearly distinct from siblings like list_competitors and search_catalog, whose ids it consumes. An agent can tell what this does and how it relates to the catalog/listing tools without opening another 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 a concrete when-to-use path: promote a listing just found in search_catalog without looking anything up in between, and it names the follow-up tool (list_competitors) with the exact condition (status 'pending' -> 'scraped'). There is no explicit when-NOT-to-use or contrast with remove_competitor, so it falls just 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?

With annotations present, the description still adds critical behavior beyond them: async rank-fetch enqueue, no position available at return, per-language independent keywords, Free/Premium quota (10/50), limit-error handling, and the ExtensionDash login requirement. No contradiction with annotations.

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

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

Front-loaded with purpose and async behavior; auth and quota are separate useful paragraphs. However, per-language tracking is stated twice (paragraphs 3 and 4), adding minor redundancy for an otherwise well-structured description.

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 returns and async flow. It does: position unavailable at return, status transitions from 'pending' to 'scanned', and where failures surface. It covers auth, quotas, and language semantics for a complex mutating 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%, so the baseline is 3. The description reinforces locale independence and quota semantics but adds little syntax or constraint detail beyond the already-detailed schema descriptions for term, locale, and extension_id.

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

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

States a specific verb ('Start tracking') and resource ('a search term for an extension'), and names sibling tools (list_keywords, remove_keyword) that handle related but distinct operations. An agent can tell it apart from read-only lookup tools without opening the schema.

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

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

Explicitly routes the agent: call list_keywords until status turns 'scanned' or list_scrape_runs to watch the fetch, and use remove_keyword to free a slot on limit errors. It also gives the required auth step, leaving nothing 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 declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so safety behavior is covered. The description adds genuine value with rank/rank_tied/rank_change semantics and the locales breakdown, but return format, pagination and size limits are not addressed. Given the annotation coverage, a 3 is appropriate rather than higher.

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

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

The core purpose and the rank semantics are front-loaded, and every later paragraph earns its place by routing to alternatives or stating auth requirements. The trailing login example is slightly verbose for an agent-facing description but remains actionable.

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 return content and does so: listings with latest numbers, tracked keywords with positions, computed rank fields, and locales with keyword counts. An agent can use the result correctly without opening anything else.

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?

Only one parameter, and the schema documents it at 100% coverage ('From list_extensions'). The description adds no further guidance on the required identifier, 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?

Opens by naming the exact resource and scope: one extension in full, with store listings' latest numbers plus tracked keywords and positions. It distinguishes itself from list_extensions (many) and get_listing (untracked) within the same paragraph.

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

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

Explicitly routes to siblings: get_metrics_history or get_keyword_ranks for movement over time, and get_listing for an extension this account does not track. It also states the prerequisite (an ExtensionDash account, with a concrete login example).

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 read-only/idempotent/non-destructive, and the description goes well beyond them: it explains that every point carries its scan depth, what a null position means for both store and Google sources, the exact Google ranking methodology (organic only, top 50, desktop, keyword-language country), and the multi-language series split. It also discloses the auth prerequisite with concrete login commands, which no annotation provides.

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

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

Front-loaded with the core purpose in the first sentence, then organized into logical paragraphs covering depth/null, language, source, and auth. Slightly long and the paragraphs are not labeled, but nearly every sentence adds information an agent needs to interpret results correctly.

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 six parameters, no output schema, and a data model involving series, depth, nulls, languages, and two sources, the description carries exactly the burden it needs to: it describes the shape of the result, the meaning of missing values, and how to authenticate. Nothing an agent needs in order to call and interpret this correctly appears to be 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 83%, so the baseline is 3, and the description adds real value on top: it defines what the 'source' enum values actually measure, explains that a term spanning multiple store languages yields one series per language (the semantics behind term/locale), and clarifies null-vs-depth semantics for the returned points. It leaves 'days' and 'store' to the schema, but those are already well documented there.

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

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

The opening sentence states a specific verb and resource (daily search position history for tracked keywords) plus the cardinality of the result (one series per term per store). It is clear what the tool returns, but it never contrasts itself with the closely related siblings get_keyword_serp and get_metrics_history, so the agent must infer which one is the historical-rank 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 rather than stated: 'tracked keywords' hints that list_keywords/add_keyword are prerequisites, and the per-source explanation implies when the 'google' source is relevant. There is no explicit 'use this when... vs. use get_keyword_serp when...' routing, and no stated exclusions or prerequisites beyond the account requirement.

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 only the safety profile (readOnly, idempotent, non-destructive, closed-world); the description adds materially new behavior: no upstream fetch or scrape credit spent, data is a point-in-time recording rather than live, rows always carry mine/competitor flags, positions are meaningless without depth_scanned, and an ExtensionDash account login is required. That auth prerequisite and the freshness/cost semantics are exactly what 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?

Purpose is front-loaded and each paragraph carries a distinct payload (what it returns, why historical, what rows carry, auth). A few constructions are stylistically padded ('no fetch, no waiting, no egress spent', the #1-of-9 vs #1-of-50 aside), but they each justify a concrete behavior, so the length is mostly 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?

With no output schema, the description does the work of describing the response (per-row mine/competitor flags, ordering, depth_scanned) and the auth prerequisite, which is strong for a 5-parameter tool. It leaves minor gaps: nothing about page/row limits, what happens if the term is not tracked, or error conditions.

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 80%, which documents term, store, locale, window, and extension_id adequately, so the baseline is 3. The description adds context about the *shape of rows* (mine/competitor flags, depth_scanned pairing) but says nothing extra about how to choose term, locale, or window values, so it does not raise the parameter bar.

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

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

The opening sentence gives a precise verb and resource ('The search page for one of an extension's tracked keywords... who was on it, in what order, and which way each of them moved over the past week'), including the temporal scope of the returned data. It implicitly separates itself from the rank-history sibling (get_keyword_ranks) by framing the result as a whole-page snapshot with movement, and from a live store fetch.

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?

'Use this when you want movement, or the same page the dashboard is showing' gives an explicit selection condition, and 'Read from recorded history, not from the store' rules out the live-fetch path with concrete consequences (no fetch, no waiting, no egress). It never names a sibling tool or states when *not* to use it (e.g. point-in-time rank trends), so it stops short of full when/when-not guidance.

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

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

Annotations already cover read-only/idempotent/non-destructive, but the description adds genuinely extra behavior: this never fetches live data, never starts tracking, is refreshed weekly with refreshed_at as the timestamp, shares a 60 calls/minute per-account quota with search_catalog, and returns null (not zero) for missing users/rating/reviews.

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, then layered with sourcing, ranking semantics, freshness, and caveats – every block is load-bearing, especially since there is no output schema. The telegraphic, fragment-heavy style ('never fetches, never answers pending') is compact but slightly harder to parse than prose.

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

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

With no output schema, the description carries the return-value burden and does so: rank/rank_tied/rank_on/rank_change semantics, refreshed_at freshness, null-vs-zero, and auth-free access. It also states the rate limit, which an agent needs to avoid throttling on repeated lookups.

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 50% – external_id is documented in the schema, while store is a self-explanatory two-value enum. The description adds the important sourcing rule that both values come from a search_catalog row, but does not restate the id format (32-letter Chrome id / AMO slug), which stays only 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?

Opens with a specific verb+resource+scope: one extension's full listing from the catalog, for any extension tracked or not, and enumerates the fields returned. It is clearly distinguishable from search_catalog (discovery) and get_metrics_history (time series for tracked extensions), both named in the text.

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 the entry path explicitly ('Pass the store and id of a search_catalog row as store and external_id') and routes the agent to the alternative ('For an extension this account tracks, get_metrics_history has its numbers over time'). It also states when not to expect a result ('never answers pending') and that no account is 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 cover readOnly/idempotent/destructive/openWorld, so the bar is lower, yet the description adds substantial beyond-annotation context: empty map means unobserved (never zero), rounding caveat via users_rounded_in_range, irregular every-few-days competitor capture, and an explicit auth requirement. This is exactly the behavioral disclosure an agent needs before trusting the numbers.

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

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

Front-loaded with what is returned and the listings/competitors split, then caveats, then auth. Every sentence carries load, though the cadence and join paragraphs are denser than strictly necessary and the login command could be trimmed.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so precisely (ISO-date-to-value maps, empty-map semantics, rounding flags). Combined with the auth, roster, and failure-mode notes, an agent has everything needed to call and interpret this tool 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 schema already documents each parameter, but the description adds meaning beyond it: store and days filter both listings and competitors, competitors implies include_competitors, and unlisted pairs hard-fail. The join key guidance (store, external_id; name is a label) further disambiguates the nested pair objects.

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?

"Daily-or-sparser history of an extension's numbers: user count, rating and ratings count, each as a map of ISO date to value" names a specific verb, resource, and return shape. It also distinguishes the two data families ("listings" vs "competitors") that the sibling list_competitors feeds, so an agent can tell it apart from 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?

Gives clear conditional routing: include_competitors for the whole roster, competitors to narrow and implies include_competitors, and warns that an unlisted pair fails the call. It also instructs how to compare a rival to listings (dates present in both). It stops short of an explicit "use X instead if..." exclusion against siblings, but the context 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 readOnlyHint/idempotent/non-destructive, yet the description still adds genuinely new behavior: data is read from positions this account already recorded, not fetched from the store, so there is no latency or rate-limit exposure. It also states each row carries its evidence and that tracked competitors retain positions even on days they drop out of results, plus the account sign-in prerequisite with concrete login commands.

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 is front-loaded and the body is organized as sets → provenance → usage → auth, with no filler. It runs slightly long, and the full sign-in command line is more instructional overhead than most callers need, but every paragraph still 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 two-parameter read tool with no output schema, the description covers everything needed to call it correctly: the shape of both returned sets, why candidates may be empty, the data source and its staleness characteristics, and the authentication requirement. Nothing material is left for the agent to guess.

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 beyond the one-line schema text: include_observed is characterized as surfacing unpromoted 'candidates' ranked by how often they beat you, and the description clarifies that promoted competitors persist through zero-visibility days. That is more than the schema conveys on its own.

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 ('Who this extension competes with, measured across every keyword it tracks') and then splits the output into two named, distinct sets. It also names the sibling add_competitor as the thing that populates the roster, so an agent can separate it from get_extension, list_keywords, and the rest of the family without reading 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?

'This is the tool for deciding who is worth promoting' gives a clear decision context, and the contrast with add_competitor implies the boundary between reading the roster and mutating it. It stops short of saying when NOT to use it (e.g. use get_keyword_ranks for a single term's positions) or that candidates require a deliberate include_observed opt-in for a reason.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds what they cannot: the required ExtensionDash account and concrete login commands, plus the shape and subtleties of the returned data (e.g., whether the store rounded the user count). With no output schema present, disclosing the return contents is genuinely load-bearing information.

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 return shape, then usage, then auth—a sensible order with no filler. It runs slightly long, and the two client-specific login examples are more verbose than strictly necessary, but every sentence still carries actionable content.

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

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

For a zero-parameter, no-output-schema list tool, the description supplies everything needed: what comes back, when to call it, and the authentication requirement. No return-value documentation is missing and no pagination concerns arise since the call is unparameterized.

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. The description correctly implies the call is unparameterized and instead scopes the result set to 'this token's owner's tracked extensions', which is the one piece of scoping semantics an agent needs.

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 ('Every extension this token's owner tracks') and enumerates exactly what each entry contains: user count (with rounding caveat), 7-day change, rating, ratings count, category rank. This distinguishes it cleanly from get_extension (single extension) and list_competitors/list_keywords (other list 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?

Provides clear entry-point guidance ('Start here when this connection has an account') and explains the downstream dependency ('every tracking tool takes an extension_id from this list'), plus the account prerequisite. It does not, however, name a specific sibling as an alternative or state a when-not-to-use condition, 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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial behavior the annotations cannot convey: the pending/scanned lifecycle, why a scanned row may carry a null position, that a pending row can still carry a stale position from a prior tracking, that removal keeps history, and the three distinct causes of a null search_volume. It also states the authentication requirement and even the login command.

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

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

The core statement is front-loaded and each paragraph covers a distinct concern (status, locale, locales, search_volume). It is long and dense, but with no output schema the return-value semantics have to live somewhere, so most sentences earn their place; only the Google Ads country enumeration feels padded.

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

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

With no output schema and only two parameters, the description carries the full burden of explaining the returned fields — status, position, captured_on, locale, locales, search_volume and its null cases — and it does so thoroughly, plus the auth prerequisite. Nothing an agent needs to interpret the response 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 meaningfully enriches the locale argument: the same term ranks differently under different store languages, and the output's locales field always reports every language even when the locale argument narrows the rows. That adds interpretive value beyond the schema's canonicalisation note.

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

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

The opening sentence gives a precise verb, resource and scope: 'Every search term tracked for one extension, one row per term per store.' An agent immediately knows this is a per-extension, per-store keyword listing. It does not explicitly contrast itself with lookalike siblings such as get_keyword_ranks or get_keyword_serp, 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?

It gives actionable operating context: 'Poll until the status reads "scanned" to know the number answers the current tracking' and 'start there to work a language at a time' for the locales field. That is clear guidance on how and in what order to use the tool, though it never names an alternative sibling or states when not to use it.

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

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

Annotations already establish read-only, idempotent, non-destructive, non-open-world behavior, so the bar is lowered. The description still adds real context: result ordering, that both listing and rank fetches appear here, the failure-vs-absent-position distinction, and a concrete authentication prerequisite with login commands.

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 blocks, front-loaded with what the tool returns before the usage hint and the auth note. Sentence count is defensible; the auth paragraph is somewhat mechanical but operationally necessary.

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, and the description compensates by naming the returned fields (outcome, error) and ordering. Auth requirements and the dual fetch-type coverage are disclosed. A brief note on default result volume or pagination would close the remaining gap for a list tool with a limit parameter.

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 limit (default 20), status (three-value enum) and extension_id documented in the schema itself. The description adds no parameter-level meaning — not even which filters are combinable or how status interacts with the run types it describes — so this sits at the baseline for partial coverage.

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

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

States a specific verb+resource ('recent scrape attempts against your own extensions') with ordering ('newest first') and return content ('outcome and any error'). It also scopes what a run covers (listing fetches and rank fetches), which separates it from get_keyword_ranks 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 an explicit trigger: 'Use this after add_keyword to watch the rank fetch,' and explains the payoff (a failed fetch surfaces as a failure instead of a missing position). It does not name a competing tool the agent should prefer in other situations, so it stops short of full when/when-not guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantive context: store fetches stop, recorded history is preserved, re-adding restores charts, and positions continue being observed via existing searches. It also discloses the authentication prerequisite with a concrete login command, which is exactly the kind of operational detail 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?

The action is front-loaded in sentence one, followed by consequences and then auth requirements in a logical order. The explanation of search-derived position observation is slightly wordy but earns its place by preempting a surprising behavior.

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 the side effects, reversibility, and auth requirement well. It does not say what a successful call returns (confirmation shape) or what happens with an unknown external_id, which keeps it short of full completeness.

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

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

With 67% schema coverage, external_id and extension_id already point to their source list tools and store has an enum. The description adds no parameter-level meaning beyond that, 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?

The first line states a specific verb and resource ('Stop tracking a competitor for an extension') with the scoping entity included. It is trivially distinguishable from add_competitor and remove_keyword by name and action. No ambiguity about what the tool does.

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 'Stop tracking' framing and the note that re-adding restores charts make the add/remove boundary clear implicitly. However, it never explicitly names add_competitor as the inverse operation or states when removal is inappropriate, so the routing guidance is contextual rather than 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 only flag destructive/idempotent; the description adds the substantive behavioral context: recorded positions survive the removal, sibling extensions and shared store listings are untouched, partitioning is per store language, and an account sign-in is required with example commands. 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?

The core action and the 'positions kept' caveat are front-loaded, with scope, isolation, and locale semantics following in descending importance. It runs slightly long across five short paragraphs, but no sentence is filler.

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

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

For a destructive mutation with no output schema, the description covers the important ground: what is destroyed versus preserved, cross-tenant isolation, locale identity, and auth prerequisites. It doesn't state error behavior for an untracked term, a minor 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 100%, and the schema already explains locale canonicalisation and the extension_id source, so the baseline is 3. The description reinforces the locale parameter's meaning ('a term is tracked per store language' with en/de independence) but adds no syntax beyond what the schema states.

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 search term for an extension') and immediately bounds the scope ('across every store it was tracked in'). The clause 'Positions already recorded are kept; only the tracking stops' distinguishes it cleanly from a delete-history operation, so an agent can separate it from add_keyword or remove_competitor 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 gives a concrete alternative for the related question ('Call list_keywords for the languages an extension already tracks') and clarifies the blast radius ('Other extensions tracking the same term are unaffected'). What is missing is an explicit when-not-to-use or a statement of what happens when the term isn't currently tracked.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds material context beyond them: 60 calls/minute per account, works without an account, nulls are not zeros, the catalog only covers what has been fetched, and the ranking is recomputed weekly with rank_change defined. This is exactly the operational context an agent cannot infer from schema or annotations.

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

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

Purpose, store choice, and the get_listing alternative are front-loaded, and nearly every sentence carries operational value. The rank/rank_tied/rank_change paragraph is dense and slightly over-detailed relative to selection needs, but it is not 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?

Despite 20 parameters and no output schema, the description explains the row fields the agent will see (listed, known, rank, rank_tied, rank_on, rank_change, owner-vs-competitor flag), which substitutes for a return-value schema. Combined with the rate limit and no-account note, an agent has enough to call it correctly on the first try.

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 20 params and only 40% schema description coverage, the description carries real weight: it explains store semantics (weekly rounded Chrome counts vs exact Firefox averages, never mixed), query word matching with all/any and punctuation/case handling, category slug behavior including rejection with a valid list, and inclusive ranges. It omits the screenshot range params and 'added'/'screenshots' sort values, which appear only in the schema enum.

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 and resource ('Search one store's catalog of extensions fetched so far'), states the scope ('one store', 'fetched so far'), and names the use case (market and niche research). The agent can immediately distinguish it from get_listing (full listing) and list_extensions (tracked 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?

Explicitly routes to siblings: 'For one extension's full listing, call get_listing' and 'pass its store and id to add_competitor to start tracking it.' Also clarifies the tool never fetches the store, so the agent knows it operates on already-collected data. It stops short of contrasting with list_extensions, which is the main remaining ambiguity.

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