crawl_results

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

Annotations already establish read-only/safe, but the description adds substantial behavior beyond them: partial=true during a run, the 10-minute post-stop window where next_cursor stays set, the exact condition for next_cursor becoming null, and the content_status lifecycle (pending/fetched/failed). This is rich, non-obvious disclosure.

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 tight paragraphs, each front-loaded with the point (what it lists, what a result contains, pagination lifecycle) and no filler. Slightly longer than strictly necessary but every 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?

With no output schema, the description fully carries the burden: it names the returned fields (url, content_status, content_url) and their meaning, plus the cursor lifecycle an agent must handle to call this correctly across runs.

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 baseline is 3, but the description adds real semantics the schema lacks: next_cursor returns only URLs kept since the last read (incremental pagination) rather than a plain continuation. Limit behavior is left to the schema, which already documents it fully.

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 (list), resource (URLs a crawl kept), and ordering/scope constraint (in the order it kept them, paginated up to limit). This clearly separates it from crawl_get (status), crawl_content (fetch body), and crawl_list (enumerate crawls).

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?

Gives explicit operational context: call again with next_cursor while partial=true, and wait up to 10 minutes after a stop. It also routes the agent onward ('pass it to crawl_content as content'). It stops short of explicitly contrasting when to prefer crawl_get or crawl_wait instead, so it is strong context rather than full when/when-not guidance.

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