gpt-image-2-mcp

Get Image Job

get_image_job

Read-onlyIdempotent

Poll a backgrounded image generation or editing job using its job ID to retrieve the result once it completes or fails.

Instructions

Poll a backgrounded gpt-image-2 job. generate_image and edit_image automatically move work that runs longer than ~20s (slow proxy / large sizes / high quality) into a background job and return a job_id instead of blocking past MCP client timeouts. Call this with that job_id until state becomes "completed" (files are already written to disk and returned inline) or "failed". While still "running", wait a few seconds between polls.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`job_id`	Yes	The job_id returned by generate_image / edit_image when they moved the work to the background.

Output Schema

TableJSON Schema

Name	Required	Description
`tool`	Yes
`error`	Yes
`state`	Yes
`images`	No	Written image files — present once the job completed successfully.
`job_id`	Yes
`elapsed_ms`	Yes
`started_at`	Yes
`completed_at`	Yes
`prompt_preview`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.3.0Sep 21, 2026

TDQS

A4.9/5.0

Behavior5/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

Deploy Server