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

With annotations only providing readOnlyHint=false, idempotentHint=false, and openWorldHint=true, the description adds valuable behavioral context: the chaining behavior ('previous turn's output image is used as the input') and the drift-reduction effect of 'keep everything else the same'. It also states what is returned. No contradiction with the annotations was found.

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?

Three sentences, no filler, and the core purpose is front-loaded. The prompt guidance and return-value note are both useful and compact. Every sentence earns its place.

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 tool is complex (10 parameters, output schema, sibling session tools), but the description covers purpose, chaining behavior, prompt strategy, and return value. The input schema documents all parameters, the output schema covers results, and annotations cover safety traits. No critical gap remains for an agent to call this correctly.

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, but the description adds meaningful guidance beyond the schema for the prompt parameter: use short, focused iterative prompts and optionally include 'keep everything else the same' to limit drift. This is practical parameter-level advice that the schema's generic prompt text does not provide.

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 action ('Apply another edit turn to an existing session') and a clear resource ('session'), while also noting that the previous turn's output becomes the next input. The phrase 'another edit turn' and 'existing session' distinguishes it from start_edit_session and edit_image without needing to reference them explicitly.

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 conveys clear context: use this tool for subsequent turns of an existing edit session, after start_edit_session has created it. It also gives actionable prompt-engineering guidance ('short, focused prompts', 'keep everything else the same') to reduce drift. It does not explicitly name sibling tools or state when not to use it, so it falls just short of a 5.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, which already signal a mutating, non-idempotent operation. The description adds valuable behavior beyond these: background job auto-migration for slow calls, inline return plus file saving, high-fidelity processing with no input_fidelity option, and lack of transparent background support. This contextualizes side effects (file writes) and asynchronous behavior, though it does not discuss potential file overwrites or concurrency implications.

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 moderately long but efficiently packed. It front-loads purpose and use cases, proceeds to key technical behaviors (mask, fidelity), and ends with the background-job fallback. Every sentence carries operational or decision-relevant information; there is no filler. A tight, organized structure that earns its length.

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 13 parameters, 2 required, and an output schema, the description covers the essential operational aspects: input types and limits, mask semantics, background constraints, model variants, output handling, and the async job pattern. It does not delve into session integration (e.g., how edit_image relates to continue_edit_session) but that is arguably beyond its direct invocation scope. Given the richness of schema and annotations, the description is adequately complete for correct invocation.

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 every parameter is already described. The description adds meaning beyond the schema: it clarifies that the mask applies to the first input image, explains that models always process at high fidelity (explaining absent input_fidelity), explicitly ties 'n' to rate limits/cost (already hinted in schema), and notes transparency limitations tied to the background parameter. This extra context lifts the value beyond the schema baseline of 3.

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?

States a specific verb ('Edit or compose') and a clear resource (images with gpt-image-2 family), lists concrete use cases (swap backgrounds, retouch products, combine reference images), and names at least one constraint (mask applies to first image). It clearly distinguishes from the sibling generate_image by focusing on editing/composition, and the mention of model family and background behavior signals its scope.

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?

Provides explicit use-case guidance ('Great for: swap backgrounds, retouch products...') and notes a limitation ('use a different model for transparent backgrounds'). However, it does not explicitly contrast with generate_image or the session-based siblings (start_edit_session, etc.), nor does it state when NOT to use it beyond the transparency note. Clear context but lacks a direct alternative-routing statement.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds valuable context: sessions are in-memory only, discarded on server restart, and calling the tool frees memory sooner. No contradictions found.

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?

Three sentences, all essential. Front-loaded with the main action, then adds usage context and benefits. No filler or redundancy.

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?

Given the simplicity (1 param, high schema coverage, output schema exists), the description covers purpose, usage, and side effects. Could mention what happens if session_id is invalid, but the idempotentHint implies safe handling.

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%. The parameter 'session_id' is well-documented in the schema with minLength and description. The tool description does not add further parameter details, which is acceptable given the schema coverage.

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?

Clearly states the tool ends an iterative-edit session and distinguishes from siblings like start_edit_session by noting it is optional cleanup. The verb 'Free' and resource 'iterative-edit session' are specific.

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?

Explicitly states when to use (to free memory sooner, keep list tidy) and when not to use (safe to skip because sessions are discarded on restart). Provides alternative: not calling the tool.

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

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

Goes well beyond the sparse annotations by disclosing that images are written to disk, returned inline, may move to a background job after ~20s with a job_id to poll via get_image_job, and that outputs above 2K are beta. Also notes the transparency limitation. No contradiction with 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?

Dense and front-loaded, but visibly redundant with the schema: the model list, size constraints, transparency limitation, and background option all appear in the input schema with nearly identical wording. The valuable additions (inline return, polling workflow, multilingual capabilities, beta caveat) could be retained while trimming duplicated schema text.

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 12-parameter generation tool with a complete input schema and an output schema, this description is operationally complete. It covers artifact handling, background job polling, model limitations, and output constraints, leaving no critical behavior for the agent to infer.

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 description coverage is 100%, so the baseline is 3. The description mostly restates schema content (model enum, size constraints, background option) without adding new parameter-level meaning. It adds some operational context, such as inline return and background jobs, but not much beyond the structured fields.

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?

States a specific verb and resource ('Generate an image from a text prompt'), names the model family, and describes the concrete output behavior (written to disk and returned inline). This clearly separates it from siblings like edit_image and get_image_job as the generative entry point.

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?

Provides clear context on when generation is suitable: model strengths (photoreal, illustrations, multilingual text), unsupported transparent backgrounds, and background-job fallback behavior. It does not explicitly name alternatives like edit_image for edits, but the generate-vs-edit distinction is strongly implied by the description and title.

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

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

Annotations already mark this as read-only/idempotent, and the description adds meaningful behavioral detail: the polling lifecycle (running/completed/failed), that completed means files are already written to disk and returned inline, and the ~20s backgrounding threshold. This goes well beyond the annotation hints.

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?

Three sentences, each earning its place: purpose, backgrounding context, and explicit polling instructions. The main action is front-loaded, and there is no redundant filler repeating the title or schema.

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 is complete for an agent invoking this tool: it explains why a job_id exists, how to obtain it, what states to expect, what to do while running, and what completion/failure means. The output schema covers return structure, and annotations cover the safety profile, so nothing essential is missing.

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 already describes job_id at 100% coverage, so the baseline is 3. The description adds extra meaning by establishing where the job_id comes from (generate_image/edit_image) and how it should be used (poll until a terminal state). It does not add format details, but for a single required string parameter that is sufficient.

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?

Opens with a specific verb and resource: 'Poll a backgrounded gpt-image-2 job.' This clearly separates get_image_job from sibling creation/edit tools like generate_image, edit_image, and the edit-session tools, which have different purposes.

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?

Explicitly explains when this tool becomes relevant: generate_image/edit_image move long-running work (>~20s) into a background job and return a job_id. It then instructs to call this tool with that job_id until completed or failed, and to wait a few seconds between polls. This is actionable and leaves little to inference.

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

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

Adds critical context beyond annotations: 'in-memory only, discarded on server restart' and 'active' sessions. Annotations already declare read-only, idempotent, non-destructive, but description explains ephemeral nature.

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?

Two sentences, no wasted words. Front-loaded with key purpose and behavior. Every sentence adds value.

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?

Given zero parameters and an output schema, the description fully covers what the agent needs: what the tool returns (list of sessions) and why it exists. No gaps.

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?

No parameters, so schema coverage is 100%. Description adds no parameter info, but none needed. Baseline score of 4 is appropriate.

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?

Description clearly states 'list active iterative-edit sessions', specifying verb, resource, and scope. Distinguishes from sibling tools like start_edit_session or continue_edit_session.

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?

Provides explicit use case: 'recover a session_id after a client reconnect'. While it doesn't explicitly exclude other uses, it gives clear context for when this tool is useful.

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

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

Annotations only say the tool is non-read-only, non-idempotent, and non-destructive. The description adds meaningful behavior beyond that: the session is stateful, it returns a session_id, each turn uses the previous turn's output as input, and the session must be explicitly ended. This gives the agent a usable mental model of an accumulating session without contradicting any annotation.

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?

Three tight sentences: the action, the continuation protocol, and the termination protocol. The most important fact (stateful multi-turn session) is front-loaded, and every sentence contributes distinct information with no filler or repetition of schema details.

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?

Given the rich input schema, the presence of an output schema, and the sibling set, the description covers everything an agent needs to correctly initiate a session: what the tool does, how to continue it, and how to end it. The output schema presumably documents the returned session_id, so the description need not repeat return details.

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 description coverage is 100%, so the structured schema already documents all 12 parameters with detailed meanings, defaults, and constraints. The description itself adds no parameter-level semantics beyond mentioning session_id and continuation flow. Per the baseline rule for high coverage, a 3 is appropriate.

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 uses a specific verb-resource pair ('Begin a stateful multi-turn edit session') and immediately differentiates itself from siblings by explaining the returned session_id is passed to continue_edit_session for iterative refinement. It also plants the session lifecycle in the reader's mind by naming end_edit_session, so an agent can distinguish this from one-shot edit_image.

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 conveys when this tool is appropriate: when the agent needs a stateful, multi-turn refinement loop where each turn consumes the previous output. It also explains the follow-up flow (continue_edit_session) and termination flow (end_edit_session). It stops short of explicitly saying 'use edit_image for single-shot edits' or listing exclusions, so it earns a 4 rather than a 5.

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