Web image search

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

The description surfaces behavioral traits beyond the readOnlyHint annotation. It explicitly calls out parallel execution, the all-time default for the date field, and the behavior of query operators ('-'), which is not inferable from the annotations or schema alone. While some rate-limit or pagination details are absent, the description meaningfully enriches the behavioral context for a tool that is already annotated as read-only.

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 presented in clearly separated paragraphs with a helpful header and line breaks that break down functionality into easily scannable pieces. Each section—purpose, language constraint, freshness, query operators—adds distinct value without tangents. The formatting makes the tool behavior easily discoverable at a glance.

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 main complexities of the tool: parallel queries, the date filter, and query operators. It gracefully relies on the schema for parameters like max_images and timeout_ms, and the presence of an output schema covers return-value expectations. There is just enough added context for correct invocation, and the couple of minor gaps (e.g., total-result cap) are not material to correctness in most scenarios.

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 for parameters is 100%, and the description complements this by explaining semantics like the interpretation of date values and how the 'queries' array drives parallel execution. It also adds the English-only constraint that is not obvious from the schema. The description would need to add similar value for all parameters, but it already fills gaps in parameter understanding.

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 verb and resource: 'Searches for images by one or more queries, executed in parallel.' It not only states what the tool does but differentiates it from siblings by highlighting parallel execution and the image-specific scope (vs web_search). The purpose is immediately clear even before reading the parameter details.

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 clearly adds contextual usage guidance, such as 'Queries must be in English ONLY,' the date field usage with explicit values ('d', 'w', 'm', 'y'), and the query operator syntax (site:, quotes, '-'). However, it does not explicitly differentiate when to use this tool versus its siblings (e.g., 'use other tools for non-image searches'), so the exclusions could have been spelled out further.

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