Inspect before you write

This is the recipe that makes the others safe. Everything here uses only read-only tools that require canvas:read, element:read, or no scope at all — and it still produces a genuinely useful audit.

Goal. Given a vague request like “have a look at my brand canvas and tell me what’s wrong with it”, produce a specific, evidence-backed answer with exact handles and a link the person can click.

Tools used. guide_search, guide_get, canvas_list, canvas_get, canvas_validate, get_canvas_image, open_canvas. All seven read-only tools, as it happens.

You finish holding. A canvas handle, a revision, a list of findings with exact node handles, and a verified review URL.

The sequence

Read the rules first


{ "name": "guide_search", "arguments": { "query": "getting started workflow inspect validate", "limit": 3 } }

Then pull the top result:


{ "name": "guide_get", "arguments": { "guideId": "getting-started" } }

Check: you got back Markdown with a guideVersion. Both tools require no scope at all, so success here confirms the transport works independently of any permission question. If this fails, nothing else will — go to Troubleshooting.

Do this once per session, not once per call.

Find the exact canvas


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

Check: you get canvases with canvas: handles, titles, roles, revisions, and node counts.

If two canvases could plausibly be “my brand canvas”, stop and ask. Picking one is the first step toward editing the wrong canvas later. The guide is explicit: never guess between candidates.

Read the full graph


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

Check: you have the complete node and connection list, and a revision.

Keep the revision. Even in a read-only session, quoting it makes your report reproducible — “as of revision rev_00291” is a claim someone can verify.

Lint it


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

With no operations, this audits the current graph. It changes nothing and consumes no idempotency key.

Check three fields, in this order:

summary.errors — structural problems. broken_connection, malformed_section, broken_generated_lineage, invalid_node_geometry, and self-referencing or mis-moded frame connections land here.
summary.warnings — things worth a human’s attention: overlapping nodes, duplicate connections, fake section headers, generated outputs with no incoming relationship, orphan media placeholders.
summary.truncated — if true, findings hit the 50-per-code cap or overlap analysis gave up on a very large canvas. Your report is incomplete and should say so.

summary.passed only means zero errors. summary.reviewRequired is the honest signal — it is true when there are errors or warnings or truncation.

Every finding carries a guideUri. That is your explanation, already written: a node_overlap finding points at gavana://guides/canvas/v1/sections-layout, which you can read with guide_get.

Look at an image, if the question needs it

If the request is about how something looks rather than how it is wired, pull the actual pixels:


{
  "name": "get_canvas_image",
  "arguments": {
    "canvasId": "canvas:abc123:brand-refresh",
    "nodeId": "node:img8q4"
  }
}

Check: you get an inline preview the model can inspect, plus a temporary full-resolution link and previewExpiresInSeconds.

Pick the node id from the canvas_get result. Guessing one costs a round trip and returns 404.

A 409 here means the image node is an empty placeholder with no stored result — generation has not finished, or never started. That is itself a finding worth reporting. It is not a reason to start a generation.

Hand back a verified link


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

Check: you get canvasId, title, and url. Access was checked before the URL was built, so the link will actually open for you.

What a good report looks like

Findings, not impressions. Handles, not descriptions.

Read canvas:abc123:brand-refresh at revision rev_00291 — 34 nodes, 21 connections.

No structural errors. Two warnings and one info finding, so this needs review rather than a pass:

node_overlap — node:a1b2 overlaps node:c3d4. Both are ordinary nodes, so this is not a Section containing children. The layout guide asks for 32 units between siblings.

unconnected_generated_output — node:f7g8 is a generated image with no incoming connection and no output parent. Its lineage is unreadable: nothing on the canvas records which prompt produced it.

unclear_connection (info) — connection:x9y8 joins two media nodes with no mode set. If that is meant to be a reference rather than a transformation, it needs mode: "reference".

Review it here: https://app.gavana.ai/…

I have not changed anything. If you want the overlap fixed, say so and I will validate a proposed move before applying it.

That last line matters. It ends the turn with a request for explicit intent instead of assuming it.

Why this works read-only

Every tool above requires canvas:read, element:read, or no scope at all. There is no path from this sequence to a write if the agent stays on these tools.

An agent doing this work should not reorganise your canvas while trying to describe it. That is the contract — stay on the read-only tools until the person asks for a change.

An agent doing this work cannot accidentally reorganise your canvas while trying to describe it. That is a boundary, not a promise.

Common mistakes

Mistake	Why it hurts
Skipping `canvas_get` and answering from `canvas_list`	The list has counts, not content. You cannot describe a graph you have not read.
Treating `summary.passed: true` as “all good”	It only means zero errors. Warnings are where the real findings usually are.
Ignoring `summary.truncated`	Your report is silently incomplete. Say so.
Guessing a node id for `get_canvas_image`	Read the canvas first. The ids are right there.
Reporting “I fixed the overlap”	On a read-only connection you did not, and could not. Report what you found.
Re-reading the guide before every call	Once per session, and again when an operation is genuinely unfamiliar.

Once the inspection habit is in place, the writing recipes are safe to attempt:

Validate a batch before applying Save a generated image Hosted tool guide