image_analysis

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 clearly states that it returns text, does not generate images, and that batch requests run in parallel ('they are analyzed in parallel, so a batch costs about the same wall time as its slowest image'). It also explains dry_run behavior ('preview the request without spending'). It does not mention rate limits or auth, but for a read-only analysis tool the key behaviors are covered.

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 thorough but not bloated. It front-loads the core purpose and then adds details about batching, prompting, and dry_run in a logical order. Each sentence contributes useful information; there is no repetition or filler. It is slightly longer than necessary, but given the complexity of multiple parameters, the length is justified.

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 tool with 4 parameters, no output schema, and no annotations, the description is quite complete. It explains when to use batching, how to use dry_run, and how to give prompts. It does not describe the return format, but since there is no output schema, that is acceptable. The only minor gap is that it doesn't mention whether the tool requires any special permissions, but that is negligible for a read-only analysis. Overall, it covers all essential aspects for correct usage.

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%, so the baseline is 3. The description adds value by explaining the distinction between single image vs. `requests`, the parallel execution benefit, the purpose of `dry_run`, and how to craft a focused prompt (specific prompt vs. general description). It also gives an example prompt directly in the parameter description. This goes beyond the bare schema definitions, justifying a 4.

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 a specific verb ('look at'), a specific resource ('images'), and the output type ('returns text, not new images'). It also gives concrete use cases (product photos, face detection, general content description) and explicitly differentiates from image generation by noting it does not create images. This clearly distinguishes it from siblings like image_generate and video_analysis.

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 provides explicit use cases ('Use to read a product photo... to judge whether... to describe any image's content') and explains when to use the `requests` parameter for batching. It implicitly excludes generation by stating 'returns text, not new images,' which helps an agent choose between this and image_generate. However, it does not explicitly name alternatives or state when not to use it, leaving some inference to the agent.

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