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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds the critical constraint 'Provide exactly one source' and clarifies that generation_result_id is preferred for Shoot Board items because the server resolves the HTTPS URL—useful behavioral context beyond 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 concise and well-structured: first sentence states the broad purpose, second provides source selection guidance, third excludes QA usage with alternatives. No wasted words, 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 read-only analysis tool with 4 parameters, clear source requirements, and explicit alternative guidance, the description is complete. It covers usage exclusions, parameter selection, and behavioral expectations without needing an output schema.

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% and each parameter has a description, but the description adds extra semantic value by mapping each source type to its intended use case (generation_result_id for Shoot Board, uploaded_file_id for Files, image_url for public HTTPS) and explaining the preference rationale. This exceeds the schema descriptions.

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 clearly states the tool's function: 'Analyze any image using AI vision' with specific use cases (manual inspection, debugging, visual description, supplemental critique). It also explicitly differentiates from sibling QA tools by stating it should not be used as the primary QA mechanism.

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?

It provides explicit when-to-use context (manual inspection, debugging, etc.) and when-not-to-use, naming alternative tools: 'for QA requests use queue_generation_result_qa first, then read_generation_result_qa.' This fully covers usage scoping.

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