Jobs

The job tools let an assistant follow the work Nodaro does for it. Almost every generation tool starts a job and returns its id at once; get_job and wait_for_job report when it finishes and where the result is, list_jobs lists your recent jobs, and diagnose_run explains a failure. All four need the jobs:read permission and cost no credits.

Job statuses

A held job ends as completed when the reviewer approves it, or as failed with a policy reason when the reviewer rejects it. A client that follows the job through the MCP tasks API sees a held job as input_required: the decision belongs to the reviewer, so do not ask the user for new parameters.

The job envelope

get_job and wait_for_job return the same structured result, the job envelope. get_asset returns it too, without input.

input is a safe subset of the request, enough to check what the model received. Nothing outside this list is included:

• prompt, the prompt as rendered, after pickers, subjects and references were folded in, and userPrompt, your own words.
• negativePrompt, and the direction and subject picker ids.
• provider, model, duration, resolution and aspectRatio.
• imageUrl, endFrameUrl, and the reference image, video and audio URLs.
• The job type.

get_job

Returns one of your jobs by id, as the job envelope. Use it to check a job every 5 to 10 seconds until it finishes.

Permission: jobs:read. Credits: free.

Returns: the job envelope.

wait_for_job

Blocks until one of your jobs finishes, then returns the job envelope. Use it instead of a tight loop of get_job calls.

Permission: jobs:read. Credits: free.

Returns: the job envelope. When the job is still running at the deadline, the status is timeout. That is not an error: call wait_for_job again, or poll get_job. A held job answers pending_review at once. For a long video render, polling get_job every 5 to 10 seconds is better than repeated waits.

list_jobs

Lists your recent jobs as structured data: status, type, output URL, error, credits and timestamps. Use it for questions such as "how many generations failed yesterday". When the user wants to see the results, use browse_gallery, which shows a grid.

Permission: jobs:read. Credits: free.

Returns: a page of jobs and a next_cursor for the next page.

diagnose_run

Explains why a workflow run or a single job failed. Pass either id: the tool tries a workflow run first and falls back to a job.

Permission: jobs:read. Credits: free.

Returns: for a workflow run, every node with its job id, type and status (nodes). This is the only tool that maps the nodes of a run to their job ids. Each failed node also carries its error message, its model, the credits actually charged (creditsActual), a failure class and a hint on how to fix it.

The class is a best guess from the error text, so treat it as guidance. Reserved credits are refunded automatically for every class except post_processing, because in that case the model already delivered its work.

When a job fails

1. Read retryable. false means the same request will fail again unchanged. That happens after a content policy block, or when the model refused the combination of settings and input media.
2. Follow suggestedProvider. When a safety filter blocked the result and the catalog has a fallback model, the job names it. Run the same prompt and references on that model instead of guessing another one.
3. Change the request when the model refused it. An error that says the model rejected these settings means the duration, aspect ratio, resolution or a reference file does not fit that model. Change them, or pick a model whose capability sheet in list_models allows the combination.
4. Retry the rest. A temporary error from the model's service stays retryable, even when its wording sounds like a validation problem.

More fixes are in Troubleshooting.