list_keywords

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

Annotations only declare readOnlyHint, so the description carries most of the behavioral burden and does it well: it explains that current_rank comes from the latest daily snapshot, that null rank means 'not ranked' rather than 'unknown', that ahead/behind are null in that case, and that the tool errors rather than returning partial rank data. This is far beyond what readOnlyHint 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?

Purpose is front-loaded in the first clause and the rest is a structured enumeration of returned fields. It is long, but with no output schema the field list earns its place; a minor tightening of the return-field run-on would help.

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?

There is no output schema, so spelling out the returned fields and the null/error semantics is necessary and done thoroughly, and the pagination behavior is noted. The only gap is guidance on when to choose this over sibling keyword tools.

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% for all four parameters, so the baseline is 3. The description adds no parameter-level detail beyond the word 'Paginated', adding essentially nothing to page, per_page, app_id, or favorites.

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 ('List tracked keywords') plus the domain ('ASO metrics'), which separates it from track_keywords, untrack_keyword, and inspect_keyword. It does not explicitly name which sibling to prefer, so it falls just short of the top band.

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 by the description (it returns tracked keywords with their metrics), but there is no explicit when-to-use or when-not-to-use statement and no routing to alternatives like inspect_keyword or get_keyword_rank_history. The 'Paginated' note hints at retrieval context but is not guidance.

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