read_urls

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

The annotation readOnlyHint is consistent with the read operation, and the description adds useful behavioral details: parallel fetching, JS rendering, boilerplate stripping, even budget splitting, duplicate merging, and skipped extras. Failure behavior is also disclosed as a failed page costing one line rather than a failed call.

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 efficient and well structured, with the high-level behavior, use case, and parameter details each getting their own section. There is minor repetition of ideas such as 'one call' and 'one round-trip', but nothing that significantly hurts clarity.

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?

The description is complete for an agent to select and invoke the tool correctly: it covers purpose, use case, parameter semantics, failure behavior, and important operational details. The presence of an output schema and readOnly/openWorld annotations reduces the need for additional output or side-effect explanation.

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?

Although the schema itself lacks property descriptions, the tool description fully compensates by explaining each parameter: urls constraints and deduplication, query as optional focus, total_chars as the combined budget, and refresh as cache bypass. This goes well beyond the bare schema and gives an agent everything needed to set parameters correctly.

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 precisely what the tool does: reads several known web pages in one call under a shared character budget. This clearly distinguishes it from sibling tools like read_url, web_search, and deep_research by emphasizing the batch and known-URL aspects.

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 recommends this tool over repeated read_url calls when the URLs are already known, and gives concrete reasons: one round-trip, one budget, and partial failure handling. This gives an agent clear, actionable selection criteria.

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