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

Despite readOnlyHint and idempotentHint annotations, the description reveals non-obvious behavior: 'They are display previews, not originals: url/download_url are originals, preview_url is the fallback link, and poster_url/thumbnail_url is a video poster.' It also warns against Markdown-embedding result URLs and mentions that raw payload is returned when available, providing significant context beyond 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 long (about six sentences) but each sentence provides necessary information for correct usage, such as URL semantics, ID handling, and confirmation-flow guidance. It is front-loaded with the purpose but the later section on confirmation clients could be separated for better scannability. Still, no sentence is wasted.

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 an 18-parameter tool with no output schema, the description thoroughly covers retrieval modes, result content (labeled ImageContent previews), URL differentiation, downstream ID usage, and date-filter examples. It addresses confirmation workflows and raw payload recovery, making it nearly self-sufficient for an agent to use this tool and understand its outputs.

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 covers all 18 parameters, so the baseline is 3. The description adds value by clarifying the generation_result_id vs generation_id usage and emphasizing that these integers are required for QA/edit/upscale/video commands. It also gives a semantic example for start_date/end_date, slightly exceeding 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 'Look up generation results by exact IDs, filters, or hybrid image/name/SKU search', clearly stating the action and resource. It further differentiates from siblings by explaining the distinction between generation_result_id (single result) and generation_id (list a job's results), which prevents confusion with get_generation_status or QA tools.

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 explicitly tells when to use downstream tools: 'Confirmation-gated clients use propose_brief(commands=[...], execute_immediately=true) when the user asked to run now, update_brief for a complete command replacement, or confirm_brief(execute=true) for a visible brief.' It also provides clear guidance for using generation_result_id vs generation_id and gives a real-world example for start_date/end_date ('last week').

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