clean_batch_scrape

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does add useful context: concurrent and async processing, a cost of 0.005 USDC, and a return format of summary and content preview. However, it omits potential failure modes, rate limits, or side effects beyond the network operation. For a scraping tool, the lack of explicit read-only or error-handling information leaves some gaps, but the provided details are helpful.

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 compact and well-organized, with the core function stated first, followed by a clear usage guideline and return summary. It avoids unnecessary filler and is front-loaded with the most critical information. The structure aids quick comprehension.

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?

Given the presence of an output schema and the tool's relatively simple purpose, the description covers the essential context: when to use it, what it does, and the output format. The only minor gap is the lack of explicit differentiation from sibling tools, but the batch aspect is clear from the 'up to 10 URLs' and the usage guideline. Overall, an agent can correctly invoke this tool.

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 covers 100% of the parameters with descriptions: 'urls' lists up to 10 URLs, and 'auth_token_or_tx' is optional. The tool description adds no new meaning beyond restating the limit ('up to 10 URLs') that is already in the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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's function: it concurrently scrapes and extracts clean markdown from up to 10 URLs. The verb 'scrapes' and resource 'URLs' are specific, and the 'up to 10' limit distinguishes it from single-URL tools like clean_web_content. The purpose is unambiguous and immediately actionable.

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 includes an explicit usage guideline: 'Use when an agent needs to perform multi-source research across multiple search results simultaneously.' This provides clear context for when to invoke the tool, though it does not explicitly list alternatives or when not to use it. The guidance is sufficient for typical scenarios.

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