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.