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.