Tool reference

Every tool the hosted MCP endpoint can offer, with its inputs — generated from the same tool table the endpoint serves.

These are the tools of the mcp surface: what a third party's agent is offered when it connects with a key. The built-in assistant in the editor runs the same tool bodies down the same execution path — which surface a tool appears on is declared on the tool itself, never filtered by an adapter, and a conformance test runs each shared tool down both paths and asserts identical payloads.

A tool marked as needing something is offered only where the deployment has that wired up: a render service, a vision provider, somewhere to keep material. A deployment without one does not offer the tool at all, rather than offering it and failing — a refusal and an absence are different signals, and a model will retry a refusal with different arguments.

vf_list_blocks

The Block vocabulary: every Block, its parameters as JSON Schema, worked examples, and the conventions that are not in the schema. Read this before writing or changing a document — vf-HTML resembles HTML and CSS but shortens and renames enough that guessing goes wrong.

No parameters.

vf_list_commands

Every command vf_apply accepts, with its input schema, and the envelope that carries them. Read this before the first edit of a session.

No parameters.

vf_list_designs

Every Artifact this key can reach, with the frames each one is made of. Call this first when you do not already hold a design id — every other tool addresses a single frame by its id, and ids cannot be guessed.

No parameters.

vf_get_doc

One frame: its canvas geometry and safe area, its brief, its off-canvas copy, and a flat list of every node with the id you address it by. Each node also reports its name, and whether it is locked or hidden — read those before planning an edit, because a locked node will refuse one. Call this before your first edit to a frame: an id names a node and does not move, so one you read here stays good, but there is no other way to learn what a frame contains. Keep the `version` it returns and hand it to vf_apply as `baseVersion`, so an edit composed against this reading is refused rather than landing on a document somebody else has changed underneath it.

Parameter	Type	Accepts	What it does
designId *	string	—	Id of one frame, as vf_list_designs returns it. Not the set id.
nodeId	string	—	Only this node and its descendants.
outlineOnly	boolean	—	Omit the document text and return only ids. Cheaper on a large frame.

vf_apply

Apply a batch of commands to one frame, as a single unit — if any command fails, none is applied, so a rejected batch is safe to fix and retry. The `version` this returns is the frame's new version: carry it into `baseVersion` on your next edit to the same frame. Anything the batch created is listed in `created`, in order — use those ids to address what you just made, including from a later command in the same batch; they are stable and will not move when something is inserted before them. This is the only way to change a document. A locked node refuses every command but node.setLocked, and so does everything inside it; you may unlock one, but do it deliberately and say so, because a lock is a decision the owner made. The `note` is required and becomes the entry in the Artifact's history that the person who owns it will read, so write what changed and why in their language, not in Block names.

Parameter	Type	Accepts	What it does
designId *	string	—	Id of one frame, as vf_list_designs returns it. Not the set id.
note *	string	—	One line, in the owner's language: what changed and why. Shown in their history.
commands *	unknown[]	—	Commands in order, applied as one unit. vf_list_commands carries a worked example of each.
view	enum	summary \| full	What to return about the frame afterwards. "summary" (the default) is the new version, the ids this batch created, and the Checks — everything you need to keep editing. "full" adds the whole document and every node, which is a large answer you will carry for the rest of the conversation; call vf_get_doc instead when you need the tree once.
baseVersion	integer	— (−∞ to 9007199254740991)	The version this frame was at when you read it. Send it: the write is then refused if anybody changed the frame since — the owner editing in their browser, or another agent — and you are told to re-read. Without it your edit lands on whatever is there now, and since node ids are positions in the tree, an id you are holding may by then name a different Block. Keeping it current is two rules: it starts as the `version` vf_get_doc returned, and every successful vf_apply returns the new `version`, which becomes the value for your next edit to the same frame. Sending the one you started with after an edit of your own refuses your own write. Omit it only for a write that is genuinely safe on top of anything.

vf_check

Run the destination Channel's compliance rules over one frame. Call it after a batch of edits and before telling anyone the work is done. On a deployment that can render, this covers the *rendered* rules too — overflow, and contrast measured against the colour actually behind each glyph rather than the one the document declares — which are the rules that decide, and the ones a document-only reading is blind to. Pass `boxes` to also get back where every node landed after layout, which is the only way to know how tall a run of text turned out. `passes` in the reply says which passes ran, and `absent` names any rule this deployment could not run at all, so a green light is never bigger than the thing that produced it. `observations` is separate from `findings` and cannot fail a frame: it is where anything reaching past the Channel's safe area is reported, which is a guide the destination publishes rather than a rule this gate enforces.

Parameter	Type	Accepts	What it does
designId *	string	—	Id of one frame, as vf_list_designs returns it. Not the set id.
channel	string	—	Check against a different Channel than the canvas implies.
boxes	boolean	—	Also return every node's real box after layout — x, y, width, height. A <vf-text> declares neither a width nor a height, so this is the only way to find out that a headline you placed at y=340 occupies 340 to 520. Costs a render.

vf_screenshot

Render one frame and return the picture. Look at a frame after you change it — the Checks catch violations, but only looking catches a headline that collides with a logo, a composition that leans, or three frames that do not read as one family.

Offered only where the deployment has render wired up.

Parameter	Type	Accepts	What it does
designId *	string	—	Id of one frame, as vf_list_designs returns it. Not the set id.
maxEdge	integer	— (128 to 2048)	Longest edge in pixels. Defaults to 1024, which is enough to judge by.

vf_look

Render one frame and answer a question about what it actually looks like. Use it for anything the document cannot tell you — whether text is readable over the image behind it, whether the eye lands where you meant it to, whether a photograph and a headline are fighting. Ask one specific question; 'is this good' gets a vague answer, and vf_critique is the tool for a full review.

Offered only where the deployment has render and vision wired up.

Parameter	Type	Accepts	What it does
designId *	string	—	Id of one frame, as vf_list_designs returns it. Not the set id.
question *	string	—	One specific question about what can be seen.

vf_critique

Render one frame and get a design review of it: a verdict, what is working and must survive a revision, and what is worth fixing. Call it after a batch of edits, alongside vf_check rather than instead of it — the Checks are the gate and say what is wrong, this is an opinion and says what is weak. Nothing it returns fails a document, and you decide what to act on.

Offered only where the deployment has render and vision wired up.

Parameter	Type	Accepts	What it does
designId *	string	—	Id of one frame, as vf_list_designs returns it. Not the set id.
intent	string	—	What this design is trying to do, if the brief does not already say.

vf_generate_image

Generate an image and keep it, returning the asset:// path to put in a <vf-image> src. Use it for the material the Block vocabulary will never draw — a photograph, a texture, an illustration — and not for anything shapes and type already do, which stays sharp at any size and can be recoloured later. Describe the picture, not the layout: composition, crop and placement are yours to decide afterwards. Pass `likeDesignId` to carry the look of a frame you already have, which is how a set of frames ends up looking like one family instead of three unrelated pictures — it also hands the picture that design’s reference palette, which outranks anything you pass in `palette`. It will not draw a QR code, a barcode or anything else meant to be scanned: a generated one cannot be read, so leave that space empty and let the person add their own — including when a reference has one.

Offered only where the deployment has vision and material wired up.

Parameter	Type	Accepts	What it does
prompt *	string	—	What the picture shows. Subject, mood, medium, palette — not where it sits.
aspectRatio	enum	1:1 \| 4:3 \| 3:4 \| 3:2 \| 2:3 \| 16:9 \| 9:16 \| 21:9	Shape of the picture. Pick the one nearest the space it has to fill — the crop is yours to set with <vf-image fit> afterwards. Defaults to 1:1.
likeDesignId	string	—	Render this frame and carry its look into the new picture — image-to-image.
palette	string[]	—	Hex colours the picture must sit inside, heaviest first. Use it whenever the picture has to belong to a design that already has a palette — a generated image brings its own colours otherwise, and they will fight the type you put on it. If the design named by `likeDesignId` was made from a reference, that reference's palette is used instead of this one and the reply says so: a replication's colours are the reference's, not yours to choose.

template_search

Find published templates by free text and fixed fields (tags, channel, locale). Returns metadata and the retrieval digest, never frames — fetch one with template_get when you have chosen.