search_and_crawl

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

Annotations set readOnlyHint=true, but the description describes writing files to disk (per-page markdown, index.json), which is a side effect. This is a direct contradiction. The description does not acknowledge or clarify the discrepancy, nor does it explain any non-destructive nature.

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 description is succinct with only two sentences, yet covers the core purpose, output mechanism, and key configurations. Every sentence adds essential information; no redundancy.

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?

Despite the complexity of combining search and crawl with many options, the description covers input, persistence, response behavior, and error handling. However, it omits details on rate limiting, timeouts, or the output schema structure, which would enhance completeness.

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?

The parameter description inside the input schema is highly detailed, explaining each key's purpose, default behavior (e.g., 'full page bodies are written BEFORE truncation'), and special cases (failed pages). This adds significant value beyond the schema structure, achieving high clarity.

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 clearly states the tool combines Google search with crawling top results, specifying verbs 'Search' and 'crawl' on the resource 'Google results'. It distinctively differentiates from siblings like 'search_google' and 'crawl_url' by highlighting the combination.

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?

Provides instructions on when to use (to combine search and crawl with persistence) but lacks explicit guidance on when not to use it or alternatives. No mention of siblings or trade-offs.

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