vision_ocr

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

There are no annotations, so the description carries the full burden. It discloses the core behaviors: visible text is extracted, the result is returned as transcription text, and detail is recommended to be 'original'. This is a read-only OCR operation and the description conveys that, though it does not explain token or input limits.

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 two short sentences, front-loaded with the main purpose and followed by a useful parameter preference. It has no filler or repetition; every sentence contributes.

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 simple OCR tool with three parameters and no output schema, the description provides the core needed context: input type, output form, and a recommended detail setting. Some gaps remain around how the image value should be supplied and how max_tokens affects the result, but the agent can safely select and invoke the 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 schema has 0% property-description coverage, so the description must compensate. It adds some meaning for the 'detail' parameter with the recommendation 'Prefer detail="original"' and clarifies the image is a screenshot/document, but it does not explain 'max_tokens', and the exact meaning of the detail enum is left to the schema.

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 clear verb and resource: 'Read visible text from a screenshot/document image' and immediately goes on to say the output is the transcription. It unmistakably identifies this as an OCR tool, distinguishing it from siblings like vision_analyze or vision_describe.

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 intended use is implied by 'Read visible text' and 'transcription,' but the description does not explicitly say when to use this tool versus the sibling vision tools, nor does it state any exclusion conditions. The only prescriptive guidance, 'Prefer detail="original"', is about parameter choice rather than tool selection.

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