search_site_and_analyze

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

No annotations are provided, so the description carries the full transparency load. It successfully discloses the core behaviors: uses external search engine, parsing through trafilatura and Qwen, handles layout changes, reports progress per match/chunk, and has long latency per match. It does not mention possible rate limits, no-match behavior, failure modes, or network auth, but covers most relevant behavioral traits for an AI agent considering this 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?

The description is well-structured into a high-level workflow, mechanism, performance note, and Args section. Every sentence contributes useful information such as time estimates, layout-resilience, or parameter semantics. It is concise without sacrificing essential guidance, and the 'Args:' list makes scanability easy.

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 multi-step search-and-analysis tool, the description covers when to use it, how it works, what each parameter means, time cost, progress reporting, and the fact that output follows analyze-style extraction. Because an output schema exists, avoiding return-value detail is appropriate. The description provides enough for an agent to decide if this tool is appropriate and set expectations about runtime.

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 input schema has 0% description coverage, so the description is responsible for parameter meanings. It provides meaningful explanations for all four params: `site` with an example domain, `phrase` as an exact phrase, `question` as what info to extract, and `max_results` as maximum matching pages with a default of 5. This fully bridges the schema gap, though some examples or constraints are minimal.

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, action-oriented phrase: 'Search a specific site for pages/listings containing `phrase`, then run `analyze_page`-style extraction on each match to answer `question`.' This clearly defines the tool's responsibility and differentiates it from the sibling tool `analyze_page`, which focuses on a single page. The scope (site-level search plus extraction) is unambiguous.

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 explicitly explains when to use it ('Works on any site without site-specific scraping code'), how it works (DuckDuckGo `site:` search, trafilatura + Qwen), and yields a practical performance caveat: 'Each match takes roughly 30s-3min to fetch and analyze.' It does not explicitly name an alternative for single-page analysis, though it references `analyze_page`-style extraction, so it provides clear context but no explicit 'when not to use' statement.

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