maginary-mcp

Run action on image

execute_action

Run a follow-up action on a completed generation's image.

After ``generate`` → ``wait_for_generation``, the response's
``processing_result.available_actions`` lists what's possible per slot.
Call this tool with one of those action types.

Args:
    generation_uuid: UUID of the parent generation (from ``generate``).
    action_type: One of the values from ``available_actions`` — e.g.
        ``"upscale_2x"``, ``"upscale_1_5x"``, ``"vary_strong"``,
        ``"vary_subtle"``, ``"pan_left"``, ``"pan_right"``,
        ``"pan_up"``, ``"pan_down"``, ``"zoom_out_2x"``,
        ``"zoom_out_1_5x"``, ``"img2img_basic"``, ``"img2img_inpaint"``,
        ``"img2vid_basic"``, ``"reroll"``.
    parent_image_index: The slot index of the image to act on (0, 1,
        2, or 3 for a 4-image grid). Required for per-slot actions;
        omit for ``"reroll"`` (global action).
    prompt: Required for ``img2img_basic``, where it is the edit
        instruction (e.g. ``"make the hat red"``; flags such as ``--2``
        or ``--flagship`` may follow it), and for ``img2img_inpaint``,
        where it is the instruction followed by ``--mask <shapes>``
        (e.g. ``"make the hat red --mask rect(.2,.1 .8,.4)"``; the
        instruction may be empty to just redo the area). Optional otherwise: for
        ``vary_*`` you can steer the variation with a new prompt; for
        ``img2vid_basic`` you can describe the desired motion.
    callback_url: Optional webhook URL (same as ``generate``).

Returns:
    The newly created child generation record (same shape as
    ``generate``'s return — poll it with ``wait_for_generation``).

    On failure, same ``isError`` contract as ``generate``:
    ``"auth"``, ``"payment_required"`` (with x402 challenge),
    or ``"failed"``.

Input Schema

Name	Required	Description
`prompt`	No	Prompt for the action. Required for img2img_basic (the edit instruction) and img2img_inpaint (the instruction, which may be empty, plus --mask <shapes>); optional replacement prompt for vary/img2vid.
`action_type`	Yes	Action from available_actions, e.g. upscale_2x, vary_strong, img2img_basic, img2img_inpaint, img2vid_basic, reroll.
`callback_url`	No	HTTPS webhook URL for done/failed notifications.
`generation_uuid`	Yes	UUID of the parent generation.
`parent_image_index`	No	Slot index (0-3) of the image to act on. Omit for global actions like reroll.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 12, 2026

changedInput schema / properties / action_type / description

Previous value: -"Action from available_actions, e.g. upscale_2x, vary_strong, img2vid_basic, reroll."New value: +"Action from available_actions, e.g. upscale_2x, vary_strong, img2img_basic, img2img_inpaint, img2vid_basic, reroll."

changedInput schema / properties / prompt / description

Previous value: -"Optional replacement prompt for vary/img2vid actions."New value: +"Prompt for the action. Required for img2img_basic (the edit instruction) and img2img_inpaint (the instruction, which may be empty, plus --mask <shapes>); optional replacement prompt for vary/img2vid."

First observedSep 15, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations are present (non-read-only, non-idempotent, open-world), but the description adds substantial context beyond them: the call creates a child generation record that must be polled, and failures follow the same ``isError`` contract as ``generate`` with ``auth``, ``payment_required`` (x402 challenge) and ``failed`` cases. That is exactly the kind of downstream-behavior disclosure annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded purpose followed by Args/Returns blocks; the 14-item action-type list earns its place because the schema defines no enum for action_type. It is longer than strictly necessary, with a few restatements of schema-documented behavior, but nothing is padding.

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?

For a multi-action, stateful tool with an output schema and annotations, the description supplies the missing connective tissue: ordering relative to generate/wait_for_generation, where to source action names, required-vs-optional parameter rules, and the failure contract. An agent has everything needed to invoke it correctly on the first try.

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?

Schema coverage is already 100%, so a 3 is the floor, and the description goes further by stating per-slot requirements (parent_image_index required except for ``reroll``) and the ``--mask <shapes>`` / flag syntax for ``img2img_inpaint``, which the schema's brief one-liner omits. Some overlap remains with the schema's own prompt and action_type text, keeping this out of 5 territory.

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?

States a specific verb and resource ('Run a follow-up action on a completed generation's image') and positions it precisely in the pipeline after generate → wait_for_generation, which cleanly separates it from both siblings. An agent can tell this is the post-generation image-editing tool without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear precondition chain (only after ``generate`` → ``wait_for_generation``) and tells the agent where valid inputs come from (``processing_result.available_actions``), plus which actions are global vs per-slot. It does not state an explicit when-not-to-use or name a competing sibling as an exclusion, so it falls 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.

All maginary-mcp tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.