Check ranks

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

Adds real behavioral context beyond the annotations: it runs as a background job, the store is rate-limited so large boards take minutes, and results from today are reused unless force is true. That caching semantic is not expressible in the annotations. The gap is that it never says how to obtain or poll the job's results (wait_for_jobs, get_project_board), which matters for an async tool.

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?

Three sentences, zero filler, with the core action first and the operational caveats (background job, rate limit, reuse rule) after. Each sentence carries distinct information.

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?

Wait — reassessing: for a mutation-ish async job with full schema coverage and no output schema, the description should say how results surface. It does not mention result retrieval or how to wait, which is a meaningful omission for a background job tool. Score adjusted to 3.

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 projectId, markets and force. The description reinforces the force=true behavior (overriding same-day reuse), adding slight nuance, but contributes nothing about markets or projectId beyond the schema. Baseline 3 is appropriate.

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: searches the store for the project's keywords and records rank, volume/difficulty and competitor data. This is clearly distinguishable from read-only siblings like get_term_detail or fetch_popularity, and the scope (every keyword in the project's markets) is explicit.

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?

The description implies when to use it (populating rank data for a project) and covers the reuse-vs-force condition, but never names alternatives or exclusions — an agent cannot tell from this text whether to use run_rank_check, fetch_popularity, or get_project_board for a given need. Usage is implied rather than guided.

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