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.