---
title: Tools
description: Every tool a connected agent may call, with what each one does and takes.
sidebar:
order: 15
---
37 tools, all scoped to the websites the token's owner can reach.
Every one takes an optional `tenant_id`, the site's friendly id as `get_site` returns
it, and works on the account's original site when it is left out; it is not repeated
under each tool below. A token that may only read is offered the 19 that ask for
no more, and `tools/list` names exactly what a connection may call.
## Reading
### get_site
**Get site overview.** Scope `site:read`, read-only.
The selected website: its friendly id, name, public address, every
live page with its path and file, the branches ahead of main
(`pending_branches`; list_branches has their preview URLs), and a
preview URL for the live site. Also its languages, its tables (with
how many `posts` are `published` beside their `records`), its
JavaScript files, and its plan: limits, usage, and whether the site
is frozen.
Takes nothing beyond `tenant_id`.
## Notifications
### list_notifications
**Read what the owner has been told.** Scope `site:read`, read-only.
What the owner has been told about this site, newest first: the alerts
on the Notifications screen of their dashboard. Each says what
happened, when (`received_at`), and whether it is still unread
(`unread`). Call it when the owner asks what is wrong with their
site or what has happened on it. `get_site` says how many are unread.
Arguments:
- `kind` (string, one of `form_submission`, `page_degraded`, `plan`, `script_failed`, `site_transfer`): Only the alerts of this kind. Leave it out for every kind.
- `unread` (boolean): true for only the alerts that are still unread.
## Vocabulary
### describe_vocabulary
**Describe the site vocabulary.** Scope `site:read`, read-only.
Everything a site's files may say, generated from the running code
rather than written down, so it is never out of date. Topic language
is the whole of vzk on one card; the rest are the platform's: looks,
behaviors, javascript, fields, meta, layout, sites and guides.
Arguments:
- `topic` (string, one of `looks`, `behaviors`, `javascript`, `fields`, `meta`, `layout`, `sites`, `guides`, `language`): Which part of the vocabulary to describe. Defaults to language.
- `name` (string, one of `apps`, `building`, `claret`, `cobalt`, `copying`, `instructions`, `mineral`, `photographer`, `photographer/blog`, `photographer/blog/[slug]`, `photographer/index`, `photographer/services`, `photographer/work`, `photographer/work/[slug]`, `playbooks/photographer`, `playbooks/plumber`, `plumber`, `plumber/index`, `plumber/prices`, `press`, `publication`, `starter`, `starter/index`, `vizitka`, `vizitka/about`, `vizitka/acceptable-use`, `vizitka/cookies`, `vizitka/data-deletion`, `vizitka/dpa`, `vizitka/index`, `vizitka/legal`, `vizitka/legal-notice`, `vizitka/pricing`, `vizitka/privacy`, `vizitka/subprocessors`, `vizitka/terms`, `vzk/authoring`, `vzk/javascript`, `vzk/languages`, `vzk/pages`, `vzk/styling`, `vzk/tables`, `vzk/tests`): With topic=looks, sites or guides, return only this one.
### check
**Check a change without writing it.** Scope `site:read`, read-only.
Says what write_files would say of a change, without writing it: up to
50 files written, deleted or moved over a branch or
a commit (default main), checked as a commit is. Answers `ok`, each
refusal under `problems` with its file, the compiler's `warnings`,
and what a write would fix and format in a .vzk file, under
`would_apply` and `would_format`.
Arguments:
- `ref` (string): A branch name from list_branches, or a commit id from log. Defaults to main.
- `files` (array of object, required): Each file with exactly one of content, delete or move_to.
- `path` (string, required): The file, such as pages/about.vzk.
- `content` (string): The whole new text of the file.
- `delete` (boolean): true to delete the file.
- `move_to` (string): A new path for the file, its text unchanged.
## Disk
### list_files
**List the site's files.** Scope `site:read`, read-only.
Every picture on this site's disk, newest first: its name, what kind of
file it is, how big it is, the public URL it is served at, and a
`reference` ready to write in a page. The favicon (the icon browsers
show in a tab) is in the list, marked `kind: "favicon"`; an ordinary
image goes on a page as `![]({assets["<key)
"]}>`, or anywhere
else a path belongs (guide vzk/pages, Pictures).
Takes nothing beyond `tenant_id`.
### get_disk_usage
**Check how much storage the site has left.** Scope `site:read`, read-only.
How much of this site's storage is used and how much is left, in bytes.
Ask before telling the owner to upload something, so "add three photos
to the gallery" does not end with them meeting a refusal you could have
seen coming. `list_files` is what is actually stored.
`picture_metadata` is what the site does with a camera's notes on the
next upload: `archive` and `discard` serve visitors a copy with them
taken off, while `publish` serves the file as it arrived, so the
camera, the moment and, from a phone, the location go out with it. Say
which one is in effect when you upload a photograph for somebody. You
cannot change it; the owner does, on the Disk screen.
Takes nothing beyond `tenant_id`.
### prepare_file_upload
**Prepare a local file upload.** Scope `site:write`, writes.
Prepares an ordinary HTTP upload for a picture that is available as a
local file but cannot be put into an MCP argument. Call this instead of
base64-encoding a local photo or icon. For a picture already at a
public https address, use `upload_file` directly instead.
Arguments:
- `kind` (string, one of `image`, `favicon`, `social_image`, required): What the file is for: image (an ordinary picture, answered with the public URL it is served at); favicon (the site's tab icon — replaces the current one, live at once); social_image (the picture a shared link to this site shows — replaces the current one, live at once, and cropped to 1200×630 from the middle).
### upload_file
**Put a file on the site's disk.** Scope `site:write`, writes.
Puts a file on this site's disk, from exactly one source: a picture the
customer attached in this conversation (`file`), a public https address
(`url`), or base64 bytes (`data`). Only raster images are accepted (PNG,
JPEG, WebP), and the bytes are identified on arrival: a file that is not
really a picture is refused whatever it is named. When the customer has
attached the picture to this conversation, `file` is the source to use:
pass that attachment and the client supplies the address. For a local
file on a machine with a shell, do not base64 it either: call
`prepare_file_upload` and POST it as multipart form data instead.
Arguments:
- `kind` (string, one of `image`, `favicon`, `social_image`, required): What the file is for: image (an ordinary picture, answered with the public URL it is served at); favicon (the site's tab icon — replaces the current one, live at once); social_image (the picture a shared link to this site shows — replaces the current one, live at once, and cropped to 1200×630 from the middle).
- `file` (object): The picture the customer attached to this conversation. When there is an attachment and it is the thing to store, pass it here and the client fills in its address. Never write a download_url of your own — a link given to you as text goes in `url` instead.
- `download_url` (string, required): A public https address the file can be fetched from.
- `file_id` (string, required): The client's own id for the file.
- `mime_type` (string): What the client believes the file is. Advisory only: the bytes are identified on arrival, and it is they that decide.
- `file_name` (string): What to call the file, when the client knows.
- `url` (string): A public https address to fetch the file from.
- `data` (string): The file's bytes, base64-encoded. A data: URL is fine too.
- `filename` (string): What to call the file. Required with data. With file the client's own name is used when this is left out, and with url the address's own last segment.
## Code
### list_tree
**List the site's files.** Scope `site:read`, read-only.
Every file of the site's code (pages, layouts, components, locales,
scripts, stylesheet, import map) at a branch or a commit, with its
kind and size. Defaults to main. Read the text with read_files.
Arguments:
- `ref` (string): A branch name from list_branches, or a commit id from log. Defaults to main.
### read_files
**Read some of the site's files.** Scope `site:read`, read-only.
The text of up to 20 files at a branch or a commit (default main),
with the commit read, which write_files takes as base. list_tree names
the files; describe_vocabulary topic layout explains them.
Arguments:
- `paths` (array of string, required): File paths from list_tree, such as pages/index.vzk.
- `ref` (string): A branch name from list_branches, or a commit id from log. Defaults to main.
### outline
**Outline the site or one file.** Scope `site:read`, read-only.
The map of a site written in vzk at a branch or a commit (default
main): its files, or with path one file's blocks, each with its
address, lines, size and note. Read one with read_block.
describe_vocabulary topic language teaches vzk.
Arguments:
- `path` (string): A .vzk file, such as pages/index.vzk, to list its blocks. Omit for the site's files.
- `ref` (string): A branch name from list_branches, or a commit id from log. Defaults to main.
### describe
**Describe what the blocks do.** Scope `site:read`, read-only.
What the blocks of a site written in vzk do, in sentences made from
their code alone, at a branch or a commit (default main): with path
every block of one file, with address one block, each with a
person's notes on it. With neither, what each file is and how many
blocks it holds. outline lists the addresses.
Arguments:
- `path` (string): A .vzk file, such as pages/index.vzk, to describe its blocks. Omit for a line on every file.
- `address` (string): One block's address from outline, such as pages/index.vzk#hero. Not with path.
- `ref` (string): A branch name from list_branches, or a commit id from log. Defaults to main.
- `manifest` (boolean): With path or address: also answer the facts under the sentences as data, under facts. Default false.
### read_block
**Read one block of a file.** Scope `site:read`, read-only.
The text of one block of a vzk file, named by its address from
outline (pages/index.vzk#hero), at a branch or a commit (default
main), with the commit read, which write_block takes as base, and
under notes what a person noted on the block.
Arguments:
- `address` (string, required): The block's address from outline: its file, # and its id, such as pages/index.vzk#hero.
- `ref` (string): A branch name from list_branches, or a commit id from log. Defaults to main.
### log
**Show the history of the site's code.** Scope `site:read`, read-only.
The commits on a branch (default main), newest first, with who made
each and a preview URL; with path, only the commits that changed that
file. revert takes a commit id from here.
Arguments:
- `ref` (string): A branch name from list_branches, or a commit id from log. Defaults to main.
- `path` (string): Only the commits that changed this file.
- `limit` (integer): How many commits. Default and most 50.
### diff
**Compare two versions of the site's code.** Scope `site:read`, read-only.
The files that differ between two branches or commits (from defaults
to main), each added, modified or deleted, with its text before and
after. diff to a branch is what merge_branch would put live. Where
the site's tables are files, `tables` says what that would do to
them, and which steps wait for the owner.
Arguments:
- `to` (string, required): The branch or commit to compare with from.
- `from` (string): A branch name from list_branches, or a commit id from log. Defaults to main.
- `paths` (array of string): Only these files.
## Branches
### list_branches
**List the site's branches.** Scope `site:read`, read-only.
Every branch of the site's code with its head commit, how many commits
it is ahead of and behind main, and a preview URL. main is what the
public site serves. Read guide vzk/authoring.
Takes nothing beyond `tenant_id`.
### create_branch
**Create a branch.** Scope `site:write`, writes.
Starts a branch of the site's code, from main or from another branch
or a commit. Write to it with write_files or edit_file; visitors see
nothing until merge_branch. Read guide vzk/authoring.
Arguments:
- `name` (string, required): Lowercase segments joined by slashes, such as agent/opening-hours.
- `from` (string): A branch or a commit id to start from. Defaults to main.
- `note` (string): One sentence, in the customer's words, kept with the commit.
### write_files
**Change files on a branch.** Scope `site:write`, writes.
Writes, deletes or moves up to 50 files on a branch as one
commit, checked first: a file the compiler refuses refuses the whole
commit. A .vzk file is fixed and put in canonical form as it is
written, and the answer says what changed. Never writes main; visitors
see it after merge_branch. Read guide vzk/authoring and
describe_vocabulary topic layout.
Arguments:
- `branch` (string, required): The branch to write, from create_branch. main is never written directly.
- `files` (array of object, required): Each file with exactly one of content, delete or move_to.
- `path` (string, required): The file, such as pages/about.vzk.
- `content` (string): The whole new text of the file.
- `delete` (boolean): true to delete the file.
- `move_to` (string): A new path for the file, its text unchanged.
- `message` (string): What the change is, in a line. Defaults to naming the files.
- `base` (string): The commit you read the files at. A file changed on the branch since then is refused, so another writer's change is never overwritten.
- `note` (string): One sentence, in the customer's words, kept with the commit.
### edit_file
**Change one passage of a file.** Scope `site:write`, writes.
Changes one passage of one file on a branch and leaves the rest as it
is, as one commit checked like write_files. `find` is copied exactly
from read_files and must occur exactly once, or nothing is written.
A .vzk file is fixed and put in canonical form as it is written, and
the answer says what changed.
Arguments:
- `branch` (string, required): The branch to write, from create_branch. main is never written directly.
- `path` (string, required): The file, such as pages/index.vzk.
- `find` (string, required): Exact text from the file, whitespace included. Must occur once.
- `replace` (string, required): What takes its place, taken literally. An empty string deletes it.
- `message` (string): What the change is, in a line. Defaults to naming the files.
- `base` (string): The commit you read the files at. A file changed on the branch since then is refused, so another writer's change is never overwritten.
- `note` (string): One sentence, in the customer's words, kept with the commit.
### write_block
**Change one block of a file.** Scope `site:write`, writes.
Replaces one block of a vzk file on a branch with new text and leaves
the rest of the file as it is, as one commit checked like
write_files. Read the block with read_block first. A block that
shares a line with other markup is refused: change it with edit_file.
The file is fixed and put in canonical form as it is written, and the
answer says what changed.
Arguments:
- `branch` (string, required): The branch to write, from create_branch. main is never written directly.
- `address` (string, required): The block's address from outline: its file, # and its id, such as pages/index.vzk#hero.
- `content` (string, required): The block's whole new text, taken literally, as read_block answers it.
- `message` (string): What the change is, in a line. Defaults to naming the files.
- `base` (string): The commit you read the files at. A file changed on the branch since then is refused, so another writer's change is never overwritten.
- `note` (string): One sentence, in the customer's words, kept with the commit.
### edit_block
**Move, copy, rename, remove, wrap, extract or add a block.** Scope `site:write`, writes.
Moves (within its file or to another), copies, renames, removes or
wraps one block of a vzk file on a branch by its address from outline,
makes it a component or puts a component back, or adds new markup at a
place, without sending the file. One commit, checked like write_files,
that may change several files. To undo it, revert to the answer's
parent with its paths. guide vzk/authoring shows each operation.
Arguments:
- `branch` (string, required): The branch to write, from create_branch. main is never written directly.
- `operation` (string, one of `delete`, `duplicate`, `rename`, `move`, `extract`, `inline`, `insert`, `wrap`, required): What to do: every operation but insert takes the block's address, move and insert a place, insert and wrap markup, rename an id, extract a name.
- `address` (string): The block's address from outline: its file, # and its id, such as pages/index.vzk#hero. Every operation but insert.
- `markup` (string): insert: the element or elements to add. wrap: one element with nothing in it, such as <div class="band"></div>, to put around the block.
- `id` (string): duplicate: the copy's id. Omit it for the next free name. rename: the block's new id.
- `name` (string): extract: the component's name, a capital then letters and digits, such as Hero. It is written to components/<name>.vzk.
- `before` (string): move, insert: the address of the block it goes before, in this file or another.
- `after` (string): move, insert: the address of the block it goes after.
- `into` (string): move, insert: the address of the block it goes inside, at its end.
- `end` (string): move, insert: the path of the file whose markup it goes at the end of.
- `message` (string): What the change is, in a line. Defaults to naming the files.
- `base` (string): The commit you read the files at. A file changed on the branch since then is refused, so another writer's change is never overwritten.
- `note` (string): One sentence, in the customer's words, kept with the commit.
### revert
**Put files back as a commit had them.** Scope `site:write`, writes.
Writes one commit on a branch that puts files (path, or up to 50
paths; without either, every file) back as they were at a commit. A
file that commit did not have is deleted. Visitors see it after
merge_branch. guide vzk/authoring explains undoing a change.
Arguments:
- `branch` (string, required): The branch to write, from create_branch. main is never written directly.
- `to` (string, required): The commit id to go back to, from log or a write's parent.
- `path` (string): Only this file. Omit it and paths to put back every file.
- `paths` (array of string): Only these files, put back together in one commit.
- `note` (string): One sentence, in the customer's words, kept with the commit.
### update_branch
**Bring a branch up to date with main.** Scope `site:write`, writes.
Replays a branch's commits on top of main so merge_branch can put it
live. A file changed on both in the same place refuses the update,
handing back its text at the fork, on main and on the branch; retry
with resolutions. Read guide vzk/authoring.
Arguments:
- `branch` (string, required): The branch to write, from create_branch. main is never written directly.
- `resolutions` (object): For each conflicting file, its whole resolved text, or null to delete it.
- `note` (string): One sentence, in the customer's words, kept with the commit.
### delete_branch
**Delete a branch.** Scope `site:write`, writes, destructive.
Deletes a branch and whatever it holds that was never merged. main
cannot be deleted, and the live site is not touched.
Arguments:
- `name` (string, required): The branch, from list_branches.
## Publishing
### run_tests
**Play a site's scenarios.** Scope `site:read`, read-only.
Plays the scenarios in a branch's or a commit's tests/<name>.test.ts
files (default main) with stand-in visitors and rows of their own;
the site's rows are never touched. Answers each scenario by name,
and for one that fails its line, what did not hold and what the
page showed. merge_branch is refused while one fails. Read guide
vzk/tests.
Arguments:
- `ref` (string): A branch name from list_branches, or a commit id from log. Defaults to main.
### merge_branch
**Put a branch live.** Scope `site:write`, writes, destructive.
Publishes a branch: main moves to it and visitors see its files at
once. Refused when main has moved since the branch was updated (call
update_branch first), and while one of its scenarios fails
(run_tests). Where the site's tables are files, merging changes them
too, and a branch with a step that waits for the owner is refused:
they merge it on their Branches screen. The branch is deleted
afterwards unless keep_branch. Undo with revert on a new branch.
Arguments:
- `branch` (string, required): The branch to put live, from list_branches.
- `keep_branch` (boolean): Keep the branch after the merge. Default false.
- `note` (string): One sentence, in the customer's words, kept with the commit.
## Languages
### set_site_languages
**Say which languages a site speaks.** Scope `site:write`, writes.
Declares the languages a site serves. This is the first call of
building a multilingual site, and nothing about languages works until
it has been made: no path prefix, no switcher, no `lang` attribute,
no hreflang, and no `locales/` catalog is read.
This takes effect at once: it is a site setting, not a draft, so the
prefixed addresses go live whether or not the pages are translated.
Send `locales: []` to go back to one language. Read
`vzk/languages` first.
Arguments:
- `default` (string): The language served on the site's plain paths, as a tag like "en" or "pt-br". The one language with no prefix of its own.
- `locales` (array of string): Every other language the site speaks, as tags: [ "uk", "ru" ]. This is the order a switcher offers them in, after the default. Listing the default here too is fine and means the same thing. An empty list un-declares every language.
## Site
### update_site_meta
**Set the site's default meta tags.** Scope `site:write`, writes.
Sets what the site's `` says by default: the description a
search result shows, who made it, the colour a phone browser paints
its chrome, and whether search engines should index it at all. Every
page of the site uses these unless that page says something of its
own in its own head.
**Live at once.** This is a site setting, not a file: there is no
branch, nothing to preview and nothing to merge, so a site-wide
`noindex` hides the whole site from search engines the moment it is
sent.
Arguments:
- `description` (string): One or two sentences about the page, shown under its title in a search result and on a shared link. Set at site level it describes the whole site.
- `keywords` (string): Comma-separated words. Search engines have long ignored these; they are here because some other tools still read them.
- `noindex` (boolean): Ask search engines to leave this out of their index. Set at site level it hides the whole site, which is for a site that is not ready to be found.
- `author` (string): Who made the site — usually the owner's own name.
- `theme_color` (string): The colour a phone browser paints its chrome with, as a CSS colour ("#101010").
- `twitter` (string): The site's X handle, with the @ ("@mirahalden"). It is what an X card credits.
- `page_fades` (boolean): Fade from one page of the site into the next instead of cutting. Off unless set, and a page's own value overrides the site's.
- `morph_refreshes` (boolean): Redraw a page that answers with itself, such as a form's thanks, in place and at the same scroll position. Off unless set, and it asks things of the site's own scripts (`vzk/javascript`).
- `translations` (object): The same fields in the site's other languages, keyed by language tag: { "uk": { "description": "…" } }. Merged per language and key by key inside it. Words only — an author and a theme colour are the same in every language.
## Tables
### create_table
**Add a table to this site.** Scope `site:write`, writes.
Gives the site a table of its own: a named set of fields, and somewhere
to put the rows. This is how a contact form gets somewhere to send
what a visitor types. It writes tables/<handle>.json on `branch`, and
merge_branch makes the table. Read `vzk/tables` first.
A reserved handle must keep what its dashboard screen reads, and may
add anything else:
The owner's Enquiries screen reads `enquiries`. It must keep at least one field of the site's choice, and it must stay `readable_by: owner` (it holds what strangers send).
The owner's Posts screen reads `posts`. It must keep `title` (text, what the post is called, in the tab and on a shared link) and `body` (markdown, the post itself), and it must stay `readable_by: public` (its records are pages of the site). By default, rows wait for a published_at date; publication is configurable.
The owner's Portfolio screen reads `portfolio`. It must keep `title` (text, the item's name), `summary` (long_text, a line about the item), `cover` (picture, the item's picture), `body` (markdown, the item's story), and `position` (number, its place in the owner's order), and it must stay `readable_by: public` (its records are pages of the site). By default, rows wait for a published_at date; publication is configurable.
Arguments:
- `handle` (string, required): A lowercase handle, such as "enquiries". This is what a `