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.