Search + Parallel Extract

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

Beyond annotations (readOnlyHint, openWorldHint), the description reveals critical behavioral traits: per-page extract failures are isolated, the tool is disabled in cloud mode, and there are token/performance trade-offs between modes. These details add significant value and do not contradict the annotations.

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 five sentences, each earning its place: purpose, mode guidance, performance trade-off, failure isolation, and cloud-mode restriction. It is front-loaded with the main purpose and wastes no words on fluff or repetition.

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 covers the key operational aspects: combined search+extract, mode selection, token costs, failure handling, and cloud availability. An output schema exists (as indicated in context signals), so the description need not explain return values. It falls slightly short of a 5 by not mentioning rate limits or Google-specific limitations, but it is complete enough for effective tool selection and use.

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% with detailed parameter descriptions, so the baseline is 3. The description adds context about default modes and token efficiency, but these largely mirror the schema's own parameter descriptions (e.g., mode enum and max_chars). The description does not introduce new parameter-level meaning beyond what the schema provides.

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 'One-shot Google search + parallel extract of the top results,' which is a specific verb-resource pairing that clearly distinguishes this tool from siblings like search (only search) and extract (only extract). The combined action is explicit and 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 gives clear guidance on when to use each mode: 'abstract' for a cheap survey and 'full' only when actual article texts are needed. It does not explicitly mention alternatives like 'for search-only use search' or warn against using this tool in cloud mode (beyond noting it is disabled), so it lacks explicit exclusions, but the context is strong.

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