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

Annotations only say it is not read-only, not destructive, and not open-world; the description goes far beyond that by disclosing that AI credits are spent at start with later stage charges, that a re-run of hand-edited clusters is refused and edits are carried over by head keyword, that concurrency is limited to one research per workspace, and that the call is PROPOSED only, returning status='confirmation_required' with action_id and plan_token until confirm_action. None of that is recoverable from the annotations or schema.

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 most decision-critical facts are front-loaded: the two modes first, then cost, then the rerun refusal, then concurrency, then the confirmation protocol. Every sentence carries operational content, though the confirmation block and the credit-charging sentence are dense and could be tightened slightly without loss.

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 12-parameter, no-output-schema, credit-spending mutation gated behind a confirmation handshake, the description covers what an agent needs before calling: mode selection, cost warning, concurrency, refusal conditions, and the full proposed-then-confirm lifecycle with the exact status and tokens returned.

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 92%, so per-parameter meaning is largely already documented and the baseline of 3 applies. The description still adds value beyond the schema by grouping parameters into the two mutually exclusive calling modes (project_id alone versus name + seed_keywords plus optional market/languages/city/budget/website_id) and by explaining the manual-edit carry-over semantics of confirm_rerun.

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 description opens with a specific verb and resource ("Start an SEO research") and immediately splits the two invocation modes: pass project_id to re-run, or pass name + seed_keywords to create-and-start. That makes it trivially distinguishable from siblings like seo_estimate and seo_project_status without opening any 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?

It gives explicit prerequisites and ordering (call seo_estimate first and quote the price), an exclusion (only one research runs per workspace at a time), a follow-up route (seo_project_status for progress), and a special-case condition with its own remedy (confirm_rerun=true for hand-edited clusters). Alternatives and when-not conditions are both named.

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