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

Annotations only declare readOnly=false, destructive=false, idempotent=false and openWorld=false; the description adds substantive context beyond that — the crawl runs client-side in the CookiePal plugin on the user's machine, the server performs no crawling, the report must be uploaded separately, and the banner must be verified and active beforehand. These are prerequisites and side effects the annotations do not 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?

The core action and the follow-up step are front-loaded, and each sentence carries information. The final sentence is somewhat repetitive, restating the local-only constraint twice ('claude.ai and Claude Code on the web run in the cloud' plus 'a crawler or browser run anywhere else does not stand in for it'), which could be tightened.

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 job-starting tool with two optional parameters and an output schema, the description covers everything an agent needs: prerequisites, environment eligibility, and the next step after the crawl finishes. Return values need not be explained because an output schema exists.

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%, and both parameters already document their meaning, defaults and limits (domainId defaults to the account's default domain, maxPages 1–50). The description adds no syntax, format or selection guidance for either parameter, so baseline 3 applies.

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 states a specific verb and resource — 'Starts a crawl of one of your CookiePal domains on the user's own computer' — and immediately distinguishes the tool's division of labour from siblings (upload_scan_report handles the result, get_scan_report reports status). An agent can identify what this does and what it does not do 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 preconditions ('Needs the domain's banner to be verified and active first, unless this is the very first scan of a domain just added with add_domain'), names the follow-up tool (upload_scan_report) and the status-checking tool (get_scan_report), and rules out whole environments (claude.ai, Claude Code on the web, any other crawler or browser). Both when-to-use and when-not-to-use are spelled out.

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