Previz/Tool reference/Tool reference · Read

    plan_chain

    by the PREVIZ team

    Price a chain

    What it does

    Check and price a chain before anything runs. A chain is a pipeline written as data: steps, each one a tool call, where a step's arguments may take an earlier step's output with {"$from": "stepId.output"}. Chainable tools and what each hands on: generate_frame (image), edit_frame (image), inpaint_frame (image), relight_frame (image), estimate_depth (depth), split_plate (plate, subject), animate_frame (take, video), render_cut (video), speak_line (audio), convert_voice (audio, video), generate_sfx (audio), generate_music (audio). A take's outputs are there once the take has finished. PREVIZ refuses a chain with a circle in it, more than 24 steps, steps more than 8 deep, more than 6 that could run at once or that wait on one step, a tool that is not chainable (with the reason), or a step it cannot price up front. Each step's number comes from that tool's own quote, so the total is the most the chain can cost; each step is also checked against this project's engine policy and your constraints. Returns the steps in the order they would run, the total, and every refusal by step. Free; nothing runs.

    Access class
    read · Reads only; changes nothing and costs nothing.
    Cost
    Free.
    Project
    Takes projectId, an id from list_projects.

    A key holds only the access classes its owner gave it, set in Account → API keys → the key's Access: a new key holds read and write, and spend needs a monthly credit cap. tools/list shows only the tools a key holds, and a call to any other is refused with INSUFFICIENT_SCOPE. A key made before access classes existed keeps what it could do then (read, write, spend and live) until its owner sets its access; produce is given, never inherited.

    Price

    Free. This tool never spends credits.

    Arguments

    projectIdstring · required
    The project, as an id from list_projects.
    stepsarray of object · required
    1–24 steps. Each is one tool call; a step's arguments may take an earlier step's output with {"$from": "stepId.output"}.
    dryRunboolean · optional
    true: answer what this call WOULD do — the route its engines would take under the project's policy, its price in every mode, whether it writes — and run nothing: nothing is written, nothing is charged.

    Unknown arguments are refused by name rather than ignored, so a misspelling never runs quietly.

    Answer

    The fields this tool's answer declares. They arrive as structuredContent, and as the same JSON in the first text block for clients that read text.

    project
    The project the answer is about: id and name.
    ok
    true when run_chain would quote this chain.
    steps
    Per step: id, tool, level (how many steps it waits behind), needs, credits, lines, tier (draft or final) and the engine-policy verdict.
    totalCredits
    The most the chain can cost: the sum of its steps' quotes.
    issues
    When ok is false: each refusal, naming its step.
    keyBudget
    For a key with a monthly cap: monthlyCap, spentThisMonth, remaining.
    wouldExceedBudget
    true when the total is over the key's remaining monthly budget.
    limits
    The ceilings a chain is held to.
    note
    A sentence for the agent about what the answer means or what to do next.

    Behaviour hints

    The hints the tool declares to clients, so an agent can decide what needs a person's approval.

    • Read-onlyYes
    • DestructiveNo
    • IdempotentYes
    • Reaches outside PREVIZNo

    Call it

    The JSON-RPC message, then the same call over HTTPS. Placeholders are in capitals.

    tools/call
    {
      "jsonrpc": "2.0",
      "id": 1,
      "method": "tools/call",
      "params": {
        "name": "plan_chain",
        "arguments": {
          "projectId": "YOUR_PROJECT_ID",
          "steps": []
        }
      }
    }
    curl
    curl -s https://mcp.aimpreviz.com \
      -H "Authorization: Bearer $PVZ_KEY" \
      -H "Content-Type: application/json" \
      -H "Accept: application/json, text/event-stream" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plan_chain","arguments":{"projectId":"YOUR_PROJECT_ID","steps":[]}}}'

    From an agent client you never write this by hand: connect it once (Claude Code, Cursor, TypeScript or Python) and ask for what you want.

    When it fails

    What the door answers instead, and what to do next. A refusal never charges.

    A call from a web page on an origin that is not allowed
    HTTP 403, JSON-RPC error -32003, before the body or the key is read. Call the door from a server, a terminal or a desktop client.
    A body that is not one JSON-RPC 2.0 message, or a batch
    HTTP 400, JSON-RPC error -32700 (unparseable) or -32600 (invalid or a batch), before the key is read. Send one message per POST with "jsonrpc": "2.0", a method and a string or number id.
    No key, a malformed key or a revoked key
    HTTP 401 with a WWW-Authenticate challenge, before any method runs, the handshake included. Stop and ask your person for a key; retrying will not help.
    An MCP-Protocol-Version header naming a version this door does not speak
    HTTP 400, JSON-RPC error -32600, naming the versions it supports. A request with no such header is accepted. Send the protocolVersion that initialize returned, or leave the header off.
    An unknown method
    JSON-RPC error -32601, "Unknown method" with the method's name. Use initialize, ping, tools/list or tools/call.
    An unknown tool
    JSON-RPC error -32602, "Unknown tool", naming tools/list. Call tools/list for the tools this door offers.
    Arguments that do not match the tool's input schema
    Protocol 2025-06-18: JSON-RPC error -32602 with the issues. Protocol 2025-11-25: a tool answer with isError set, naming each issue. Fix the named arguments. Unknown arguments are named, never ignored; confirm sent as the text "true" is refused, never coerced.
    A project id this key cannot reach
    A tool answer with isError set, beginning PROJECT_UNREACHABLE, naming the cause (a key limited to other projects, a role below editor, a project outside the key's reach) and list_projects. Use an id from list_projects, or ask the key's owner to widen its access in Account → API keys.
    A tool whose access class the key does not hold
    A tool answer with isError set, beginning INSUFFICIENT_SCOPE, naming the class the tool needs and the classes the key holds. Nothing ran and nothing was charged. Ask the key's owner to add it in Account → API keys → the key's Access; spend needs the key's monthly cap first.
    A refusal only a person can lift: the person's credits ran out (INSUFFICIENT_CREDITS), a monthly cap is missing or reached, a key lacks an access class, a freeze, or a spending agreement that was revoked, expired or does not cover the call
    The refusal carries actionUrl and actionLabel: the exact PREVIZ page for the person to press on, behind their own sign-in. For an agreement to sign again, the page opens with the old agreement's numbers suggested. A run answered by a job handle (a queued job, a long render) carries the same two fields on its job: get_job, list_jobs and the job's event. Nothing ran and nothing was charged. Hand the person actionUrl as it is. After they act, send the same call again with the same quoteToken or idempotencyKey. Two cases take a new idempotencyKey instead: a key whose first call already ran under an earlier agreement, and a queued job that has ended.
    A spend sent with your own idempotencyKey by an API key that has neither a monthly credit cap nor a signed spending agreement covering the call
    A tool answer with isError set, beginning CAP_REQUIRED, with actionUrl (the key's cap) and agreementUrl (the signing page). It is answered before anything is written, so the idempotencyKey is not used up. Nothing ran and nothing was charged. Hand the person either page. Once they have set a cap or signed an agreement, send the same call again with the same idempotencyKey.
    A production op from a connector sign-in, or a production this key did not start
    A tool answer with isError set, beginning with PRODUCE_KEY_ONLY (productions are driven by an API key with the produce scope) or PRODUCTION_NOT_FOUND (a key presses only the productions it started; it may read any in a project it reaches). Nothing ran. Use an API key with produce; list_productions marks the ones this key started (startedByThisKey).
    Approving words sent to a production while a price is open ("go", "approved")
    Not an error: status input_required with code WORDS_NEVER_MOVE_MONEY and the decision waiting. The words were not sent and nothing was charged. Answer the priced decision with decide {needKey, choice} under a spending agreement (mandateId), or without one for an approvalUrl a person presses on PREVIZ.
    A priced production decision with no spending agreement, or past its limits
    Not an error: status input_required with approvalId, approvalUrl and productionId. The person's press on PREVIZ answers the decision in the production itself. Nothing was charged. Hand the person approvalUrl and call await_approval; then read get_production. Nothing is run again by the agent.
    A production decision that moved on, a choice that is a person's own, or a likeness
    A tool answer with isError set, beginning with DECISION_CHANGED, PERSON_ONLY_CHOICE or LIKENESS_IS_A_PERSONS. Nothing was charged or sent. Read get_production for the decisions as they stand; a person's own choice (their billing, a handover, a likeness) is made by them in PREVIZ.
    A production PREVIZ is reading at that moment, or Produce paused on PREVIZ's side
    A tool answer with isError set, beginning with PRODUCTION_BUSY or PRODUCE_PAUSED, with retryAfterMs. Never the request's fault; nothing was charged. Send the same call again after retryAfterMs.
    A test key naming any project but its sandbox, a live key naming a sandbox project, or a test-only tool called with a live key
    A tool answer with isError set, beginning PROJECT_UNREACHABLE (a test key reaches only its sandbox project; a sandbox project is reached only by test keys) or TEST_KEY_ONLY. Nothing ran. Call list_projects for the project this key reaches. To work on a live project, use a live key; to try a tool for free, use a test key against the sandbox.
    A webhook endpoint whose URL is not https on port 443, carries a user name, or resolves to a private address; or a call for an endpoint this key did not subscribe
    A tool answer with isError set, beginning URL_REFUSED (subscribe_webhook; nothing was subscribed), WEBHOOK_NOT_FOUND, WEBHOOK_INVALID (an unknown event kind) or WEBHOOK_LIMIT (ten endpoints per key). Give a public https URL that answers 2xx itself (a redirect is never followed), name kinds or families from the subscribe_webhook reference, and read list_webhooks for this key's endpoints.
    A read of project memory that could not be made, an entity or decision that is not in this project, or more proposals than a person can be asked to decide
    A tool answer with isError set, beginning BRAIN_UNAVAILABLE (memory could not be read just now, or this part of it is not installed yet), BRAIN_NOT_FOUND, BRAIN_INVALID or PROPOSAL_LIMIT. Nothing was written or charged. Read list_decisions and get_entity for the ids this project holds. A proposal waits for a person in PREVIZ: read the ones already waiting before sending more.
    A replay that cannot be made exactly: a job whose request is no longer kept, a tool that changed shape, a policy that now leaves it no engine, or stale work that changed since its quote
    A tool answer with isError set, beginning REPLAY_UNAVAILABLE and saying which. Nothing ran and nothing was charged; PREVIZ never runs it on a different engine or from a guess. For replay_stale, call it again for a new plan and quote. For replay_job, call the tool yourself with the arguments you want.
    A tool that a rule for agents says is never run: the organisation's rule, or the person's own
    A tool answer with isError set, beginning GOVERNANCE_DENIED, naming whose rule it is. The call is refused before its arguments are read: nothing was priced, run or charged. get_governance lists every rule that binds this credential. An owner or admin changes the organisation's rule in PREVIZ; a person changes their own in their account.
    resume_chain on a chain that cannot carry on: cancelled, ended, past its quote, or stopped on a step that was charged or has used its attempts
    A tool answer with isError set, beginning CHAIN_STATE (or CHAIN_NOT_FOUND for a chain this credential did not start). Nothing ran and nothing was charged. replay_job on the chain's jobId quotes the same chain afresh; get_job reads what the chain already made.