Hosted tool guide

The hosted tools reference is generated from the application’s capability module and answers which tools exist. This page answers how to call them. Every parameter below is taken from the tool’s registered input schema, so the types, bounds, defaults, and required-ness are the ones the server actually enforces.

Four tools here — guide_search, guide_get, canvas_validate, and canvas_apply_batch — are the load-bearing ones for safe canvas work and had no documentation before this page.

How to read the parameter tables

• Required means the schema has no default and no .optional(). A missing required parameter fails input validation before the handler runs, and the error names the exact field.
• Every string bound is a character count. Every numeric bound is inclusive.
• Tools that write take an idempotencyKey of 8–200 characters. Reuse it only when retrying the identical payload; a changed intent needs a new key.
• A tool call that fails scope checks returns insufficient_scope with HTTP 403 and a WWW-Authenticate challenge naming what to reconnect with. It never partially applies.

guide_search

Search the canonical Gavana Canvas Agent Guide. This is the first call an agent should make in a session, and the call to make again whenever an operation is unfamiliar.

The guide is served from the application, not from documentation, so it cannot drift from the behaviour it describes. It is versioned — guide version 1.0.0 at the time of writing — and every result carries that version.

Read-only. Requires no scope at all — it works on a token with the narrowest possible grant. No provider cost.

Parameters

What it returns

{
  "guideVersion": "1.0.0",
  "indexUri": "gavana://guides/canvas/v1/index",
  "query": "delete a node safely",
  "results": [
    {
      "id": "existing-canvases",
      "title": "Editing Existing Canvases Safely",
      "description": "Preserve user structure, concurrent edits, and unrelated content while making scoped changes.",
      "uri": "gavana://guides/canvas/v1/existing-canvases",
      "score": 21
    }
  ],
  "availableGuideIds": ["getting-started", "notes-text-sections", "..."]
}

availableGuideIds is always the complete list of topic IDs, regardless of how the search scored. If a search returns nothing useful, pick an ID from that list and call guide_get directly.

How matching works

The query is lowercased and split on non-alphanumeric characters. Tokens of one character are discarded. Each surviving token scores against each topic:

Topics scoring zero are dropped, results sort by score then by ID, and the list is capped at limit and at 10 overall. This is deterministic lexical scoring — there is no embedding model behind it, so exact vocabulary matters. Searching overlap finds the layout topic; searching things bumping into each other does not.

The ten topics

Worked example

{ "name": "guide_search", "arguments": { "query": "section header overlap layout", "limit": 3 } }

Returns sections-layout and notes-text-sections at the top. Follow with guide_get on the winner.

When it fails

guide_get

Read one full guide topic as Markdown.

Read-only. Requires no scope. No provider cost.

Parameters

What it returns

{
  "id": "paid-action-safety",
  "title": "Paid Action Safety",
  "description": "Separate preparation from execution and prevent accidental or repeated provider charges.",
  "uri": "gavana://guides/canvas/v1/paid-action-safety",
  "mimeType": "text/markdown",
  "guideVersion": "1.0.0",
  "markdown": "# Paid Action Safety\n\nGuide version: 1.0.0\n\n## Intent boundary\n..."
}

Passing index returns the guide index — a Markdown list of every topic with its description and URI — with id set to index.

Resources versus tools

A client that supports MCP resources can list and read the same content under gavana://guides/canvas/v1/, including the index at gavana://guides/canvas/v1/index. The two paths return identical Markdown and the same guide version, so use whichever your client supports. Tool-only clients lose nothing by using guide_search and guide_get.

Worked example

{ "name": "guide_get", "arguments": { "guideId": "index" } }

Then follow a URI straight from the index:

{ "name": "guide_get", "arguments": { "guideId": "gavana://guides/canvas/v1/connections" } }

When it fails

canvas_validate

Lint a canvas, or dry-run a proposed batch of operations against the real server-side engine without applying it. This is the single most useful tool on the hosted surface and the one most often skipped.

Read-only. Requires canvas:read. No provider cost.

Validation never mutates the canvas and never consumes an idempotency key. You can call it as many times as you like.

Parameters

Two modes

Audit mode — omit operations. The server reads the canvas and lints the current graph.

Dry-run mode — pass operations. The server runs the canonical operation engine with validateOnly set, producing the graph that would exist, then lints that. Nothing is persisted and no idempotency key is consumed.

What it returns

Audit mode:

{
  "guideVersion": "1.0.0",
  "scope": "current",
  "canvas": {
    "handle": "canvas:abc123:my-canvas",
    "revision": "rev_00291",
    "nodeCount": 34,
    "connectionCount": 21
  },
  "summary": {
    "errors": 0,
    "warnings": 2,
    "info": 1,
    "truncated": false,
    "passed": true,
    "reviewRequired": true
  },
  "findings": [
    {
      "code": "node_overlap",
      "severity": "warning",
      "message": "node:a1b2 overlaps node:c3d4.",
      "nodeHandles": ["node:a1b2", "node:c3d4"],
      "guideUri": "gavana://guides/canvas/v1/sections-layout"
    }
  ]
}

Dry-run mode returns the same validation shape plus three extra keys: currentCanvas (the graph as it stands today), proposal (what the operations would produce), and destructiveImpact.

Reading the summary

summary.passed is true when there are zero errors. It is not a green light on its own.

summary.reviewRequired is true when there are errors, or warnings, or findings were truncated. Treat reviewRequired: true as “a human or the agent must look at this before writing”, and treat a warning you intend to keep as something to explain rather than silently ignore.

summary.truncated means findings hit a per-code cap of 50 and the list is incomplete; truncatedCodes names which codes were cut. Overlap detection also gives up and marks itself truncated on very large or very spread-out canvases — it buckets nodes into a 2,048-unit grid, refuses any node spanning more than 64 cells, and stops after 100,000 pairwise comparisons.

Every finding code

Every finding carries a guideUri pointing at the guide topic that explains the rule, so an agent can resolve a finding without asking.

destructiveImpact

Present only in dry-run mode. It is the deletion summary you should show a human before applying anything:

{
  "deletedNodeHandles": ["node:a1b2"],
  "deletedConnectionHandles": ["connection:x9y8"],
  "mediaNodeHandles": ["node:a1b2"],
  "generatedNodeHandles": ["node:a1b2"],
  "findings": []
}

mediaNodeHandles flags deletions of image or video nodes. generatedNodeHandles flags deletions of nodes that were produced by a generation run, an AI job, an Action, or a variation — in other words, work that cost something to make. A non-empty generatedNodeHandles deserves an explicit confirmation, not a summary line.

Worked example

Audit an existing canvas before proposing anything:

{ "name": "canvas_validate", "arguments": { "canvasId": "canvas:abc123:brand-refresh" } }

Dry-run a proposed deletion, pinned to the revision you read:

{
  "name": "canvas_validate",
  "arguments": {
    "canvasId": "canvas:abc123:brand-refresh",
    "baseRevision": "rev_00291",
    "operations": [{ "type": "node.delete", "nodeId": "node:a1b2" }]
  }
}

The full sequence is on Validate a batch before applying.

When it fails

canvas_apply_batch

Apply related node and connection operations atomically against one exact canvas revision. This is the only way the hosted server writes to a canvas graph.

Not read-only. Annotated destructive. Requires canvas:read and canvas:write. No provider cost — a batch never starts generation.

Atomic means all or nothing. If one operation is rejected, the canvas is untouched — there is no partial graph to clean up.

Parameters

Operation shapes

The tool’s own schema accepts operations as free-form objects and defers to the canonical Canvas API engine, which enforces these eight shapes. Full field-level schemas are on the Canvases API resource.

A node is one of four types — image, video, text, sticky — with title (max 160), position, width and height (each 40–10,000), and metadata. A connection carries an optional mode of list, reference, first-frame, or last-frame; omit mode for a plain dependency flow.

Node and connection references accept node:<id>, a bare id, or client:<clientId>.

Batch-local client: references

Within one batch you can connect nodes that do not exist yet. Give a node.create a clientId, then reference it as client:<clientId> from a later operation in the same batch:

{
  "canvasId": "canvas:abc123:brand-refresh",
  "baseRevision": "rev_00291",
  "idempotencyKey": "brief-and-generator-2026-08-04-01",
  "operations": [
    {
      "type": "node.create",
      "clientId": "brief",
      "node": {
        "type": "text",
        "title": "Campaign brief",
        "position": { "x": 2400, "y": 200 },
        "width": 480,
        "height": 320,
        "metadata": { "content": "Warm, editorial, no hard shadows." }
      }
    },
    {
      "type": "node.create",
      "clientId": "generator",
      "node": {
        "type": "image",
        "title": "Hero variations",
        "position": { "x": 2960, "y": 200 },
        "width": 512,
        "height": 512
      }
    },
    {
      "type": "connection.create",
      "clientId": "brief-to-generator",
      "from": "client:brief",
      "to": "client:generator"
    }
  ]
}

This is why a batch is worth building even for two nodes: creating them separately leaves a window where the graph is connected to nothing.

What it returns

The apply result — including the new revision and the created handles — plus a validation block. The server runs the graph validator on the post-write canvas automatically and returns it in the same response, so you do not need a second canvas_validate call just to see the outcome.

Read validation.summary.reviewRequired on every write. A batch can be structurally valid and still leave a warning worth reporting.

Hard rules the engine enforces

• Media content is server-owned. You cannot write image or video bytes, storage keys, or arbitrary media URLs into metadata.content. A non-empty metadata.content is rejected when the node is, or is becoming, an image or video. Use save_image_to_canvas or a generation tool.
• A Section is a text node with metadata.isSection set to true, at least 200 × 160. Anything else marked as a Section is a validation error.
• Geometry is bounded. Width and height 40–10,000. Positions must be finite.
• 200 operations maximum, 1 minimum.

Idempotency and conflicts

One stable key per intended payload. Retrying the identical batch with the same key is safe. If your intent changes — you corrected a position, added an operation, rebased after a conflict onto a different graph — use a new key. Reusing a key for a different payload is the one way to get a confusing result.

On 409, the canvas moved after you read it. Do not retry blindly:

1. Call canvas_get again.
2. Look at what changed. Someone else’s work is now in the graph.
3. Rebase your intended addition around it, preserving their change.
4. Apply again with a new key if the payload changed.

Worked example

The complete read → validate → apply → verify sequence, including how to handle a 409 mid-flight, is on Validate a batch before applying.

When it fails

canvas_list

List the canvases you own or can access, with exact handles, roles, revisions, and graph counts. The correct first call when the user has not named a canvas.

Read-only. Requires canvas:read. No provider cost.

{ "name": "canvas_list", "arguments": { "limit": 25 } }

When it fails. A 403 means the token lacks canvas:read — reconnect. An empty list on an account that has canvases means the token is delegating a different account than you expect; check which account you approved during OAuth.

canvas_get

Read the complete graph and current revision of one canvas. Call this before reasoning about or changing any existing canvas — the revision it returns is what makes a later write safe.

Read-only. Requires canvas:read. No provider cost.

Keep the returned revision — it is the baseRevision for canvas_apply_batch and for a canvas_validate dry-run.

When it fails. 404 means the handle is wrong; get it from canvas_list rather than reconstructing it. 403 means the token cannot read that canvas, which on a shared canvas may mean your role changed.

get_canvas_image

Read one image node and return an inline preview the model can actually look at, plus a temporary full-resolution link.

Read-only. Requires canvas:read. No provider cost.

Call canvas_get first when the user has not identified which node they mean. Guessing a node id here wastes a round trip at best.

What it returns

A structured block with the node handle, asset id, title, media type, width, height, a scoped previewUrl, and how many seconds that preview stays valid — plus the image itself, inlined so the model can inspect it, and a resource link.

The inline copy is re-encoded as WebP, capped at 2,048 pixels on the longest edge at quality 88. If that still exceeds 5 MB it is retried at 1,536 pixels and quality 72. The preview URL is validated to be a Gavana-origin scoped asset URL with exactly one token query parameter and nothing else, so a compromised upstream cannot redirect the client somewhere arbitrary.

When it fails.

open_canvas

Return a verified browser link to a canvas. It checks access first, so the link you hand a human is one that will actually open.

Read-only. Requires canvas:read. No provider cost.

Returns canvasId, title, and url. This is how an agent should end any turn that touched a canvas: with a link the person can click.

When it fails. 404 for a bad handle. A 502 means the service returned a canvas without an id or owner, which is a server-side problem — report the X-Request-ID rather than retrying.

save_image_to_canvas

Download one public HTTPS image, verify it, store it in Gavana, and add it as a durable image node. This is how an image created elsewhere — in ChatGPT, or at any public URL — becomes real canvas content with a node: handle you can pass to other tools.

Not read-only. Requires canvas:read, canvas:write, asset:read, and image:generate. No provider cost.

Parameters

Supplying neither image nor imageUrl fails validation with “Provide an image file or imageUrl.”

Worked example

{
  "name": "save_image_to_canvas",
  "arguments": {
    "imageUrl": "https://example.com/hero-draft.png",
    "destination": "agent-canvas",
    "title": "Hero draft — warm editorial",
    "idempotencyKey": "hero-draft-2026-08-04-01"
  }
}

Keep the returned node: handle. It is what generate_video wants as a firstFrame, and what create_canvas_workflow wants as a sourceNodeId default. The full flow is on Save a generated image.

When it fails. A non-HTTPS URL fails validation immediately. A URL that 404s or serves something that is not a raster image fails at fetch or sniff time — fix the URL rather than retrying. insufficient_scope almost always means the missing scope is image:generate.

create_canvas_workflow

Create a private, reusable Recipe and a workflow card on a canvas. This writes the workflow graph and never starts generation — that separation is deliberate, and it is what lets an agent build something on request without spending anything.

Not read-only. Requires canvas:read and canvas:write. No provider cost.

Parameters

The schema is strict — an unrecognised key is rejected rather than ignored.

Each input object:

Each output object:

The pattern that makes reuse work

Save the fixed images first, then reference them:

1. save_image_to_canvas for each image that stays the same every run. Keep the node: handles.
2. create_canvas_workflow with those handles as sourceNodeId and useAsDefault: true.
3. Later runs pass only the inputs that change.

Get this wrong and every run has to re-supply the product shot.

Returns the workflow — including its workflowNodeId and a browser url — and the canvas. Keep workflowNodeId; it is the only thing run_canvas_workflow accepts.

When it fails. A strict-schema rejection names the unexpected key. An image-typed input carrying value instead of sourceNodeId is the most common mistake. An output whose inputKeys names a key that no input declares is a modelling error worth catching before you build the card.

run_canvas_workflow

Run a workflow card, passing only the inputs that should change.

Not read-only. Requires canvas:read, canvas:write, asset:read, image:generate, and job:manage. Strict schema.

Asynchronous by design

The tool waits up to waitSeconds for the run to finish. If it does, you get the completed run with image outputs — each with a scoped preview. If it does not, you get the queued run back with its status, the destination, and the workflowNodeId.

A timeout is not a failure. Poll get_canvas_workflow_run with the returned run: handle. Do not call run_canvas_workflow again — that starts a second paid run.

Worked example

{
  "name": "run_canvas_workflow",
  "arguments": {
    "destination": "canvas:abc123:product-shots",
    "workflowNodeId": "node:wf7k2m",
    "inputs": { "background": "matte terracotta, soft window light" },
    "idempotencyKey": "terracotta-run-2026-08-04-01",
    "waitSeconds": 45
  }
}

The full sequence is on Run a canvas workflow.

When it fails.

get_canvas_workflow_run

Check or resume one workflow run. Call it repeatedly while the run is queued or running.

Not annotated read-only — it participates in run lifecycle rather than being a pure read. Requires canvas:read and job:manage. No provider cost — polling never charges. Strict schema.

A succeeded run with image outputs comes back with each output resolved to its canvas node, including a scoped preview the model can inspect.

When it fails. 400 “not a reusable workflow run” means the handle belongs to a different kind of run — check you did not pass an image job handle. A malformed handle fails the regex before any request is made.

generate_image_in_canvas

Create an image-generation target on a canvas, queue the connected provider, and wait briefly for a durable result.

Not read-only. Requires canvas:read, canvas:write, asset:read, image:generate, and job:manage.

count is the parameter to be careful with. Four images is four times the cost, and the approval you got was probably for one.

Gavana prepares the destination and the target nodes before queueing, so the canvas shows where the result will land even while it is still generating. On timeout you get the queued job plus the destination and target node ids — poll rather than re-calling.

When it fails. A conflict on target preparation (“Automatic image targets are incomplete”) means a previous partial attempt reused this idempotency key — use a new key. A terminal provider failure is reported and stops there.

find_video_models

Find connected video models and their capabilities. Always call this before generate_video, because a guessed model handle reaches the provider layer rather than failing validation.

Read-only and free, but requires the video:generate scope. Looking up a model mutates nothing; discovering video models is still part of the generation path, so a token without video:generate cannot call it.

Match capability to the inputs you actually intend to pass. If a first frame is required, ask for video.generate.fromImage — a model that only supports text-to-video will accept the call and ignore your frame.

{ "name": "find_video_models", "arguments": { "query": "Seedance", "capability": "video.generate.fromImage", "limit": 5 } }

Take a model: handle from the result verbatim.

When it fails. An empty result means no connected model matches — the user has not connected that provider. Say so; do not substitute a different model. 403 means the token lacks video:generate.

generate_video

Start a video generation with an exact connected model.

Not read-only. Requires canvas:read, asset:read, video:generate, and job:manage. Note that canvas:write is not required — the video job writes its own output rather than the caller editing the graph.

Starting from an image you have in the conversation

Call save_image_to_canvas first, then pass the returned node handle as firstFrame and the same canvas as destination. A video cannot start from an image that only exists in the chat.

{
  "name": "generate_video",
  "arguments": {
    "model": "model:seedance-2-pro",
    "prompt": "Slow push in, warm afternoon light, no camera shake.",
    "destination": "canvas:abc123:product-shots",
    "firstFrame": "node:img8q4",
    "durationSeconds": 6,
    "idempotencyKey": "hero-video-2026-08-04-01",
    "waitSeconds": 45
  }
}

On timeout you get a resumable job: handle. Poll get_video_job; never re-call generate_video.

When it fails.

get_video_job

Check or resume one video job.

Not annotated read-only. Requires job:manage only. No provider cost.

A succeeded job returns its protected Gavana output link, served through a Gavana-origin URL rather than a raw provider URL.

When it fails. 400 “not a video generation” means the handle belongs to an image job. A malformed handle fails the regex locally. If a job never leaves queued, report the state — do not start a second video.

Not on the hosted server

If you need node-level surgery (node_create, node_move, connection_delete), deterministic credit-free image action_* tools, Recipe Library search and forking, asset listing, canvas rendering, or provider discovery, those exist only on the local stdio server. See the local tools reference and Other clients.