The pages tool

Connect Claude, Cursor, or any MCP client (see Using MCP) and the agent gets one pages tool. It is an authoring and discovery tool, with these actions:

• list — see the Pages in the workspace.
• get— read one Page’s spec and declared queries.
• validate — run the verifier as a dry run, no write, just the verdict.
• create — store a new Page (its spec must pass the verifier).
• update— replace an existing Page’s spec or queries (also re-verified).
• archive — retire a Page so it leaves the sidebar (reversible; the default way to remove a Page).
• delete — permanently hard-delete a Page. Destructive and not reversible, so it needs the dedicated pages:delete scope; confirm with the user first and prefer archive unless permanent removal is intended.

The emit, validate, fix, create loop

The whole point of exposing validate separately from create is to give the agent a tight feedback loop. A well-behaved agent does not guess and ship; it iterates:

1. Emit. The agent writes a first draft spec — a tree of catalog components bound to its declared queries — following the contract in Authoring.
2. Validate. It calls validate. The verifier runs — spec shape, bindings resolve, any Custom-node code, query validation — and returns a verdict with reasons (plus a flag for whether the spec uses Custom nodes).
3. Fix.If validate failed, the agent reads the rejection (“unknown component type Timeline,” “binding $query: revenuenames an undeclared query,” “Custom node needs pages:admin”) and rewrites just that part.
4. Create. Once validate passes, the agent calls create. Because both actions share one verifier, a spec that validated will store, and the Page appears in the sidebar for everyone its grants allow.

This loop is why an agent can reliably produce a working Page: it never has to get it right on the first try, it just has to converge, and the verifier tells it precisely what to change each round. Composing from the catalog is the path of least resistance — an agent reaches for the admin-gated Customnode only when the catalog genuinely can’t express the layout.

Hand the user the link

Every list, get, create, and update response carries a console_url— the workspace link to open that Page in the console. When you build or change a Page for someone, surface that URL to them so they can click straight through to it; you never have to construct the link yourself. It is nullonly if the workspace slug can’t be resolved, and archive / delete don’t return one — the Page is gone.

Reading Pages with page://

Pages are also readable as resources. An agent can read a Page over the page:// resource scheme, page://listto enumerate the workspace’s Pages and page://<id> to pull one Page’s spec and declared queries. This is the same information list and getreturn, surfaced the resource way for clients that prefer reads as resources. It’s how an agent inspects an existing Page before updating it, or learns the house style by reading a spec someone already built.

What is not on MCP

One thing is deliberately absent from the agent surface:

• Render. An agent authors Pages; it does not render them. Rendering happens in the host, inside the sandbox, for a human viewer (see Overview). There is no “run this Page and give me the pixels” action.

Delete used to be off MCP, but hard delete is now an agent action — the delete action, gated by the dedicated pages:delete scope. This brings the pages tool to the same full-CRUD parity Amdahl already gives agents over artifacts and the knowledge base. It stays a deliberate, separately-scoped step: archive (reversible) is the default, so choose archiveunless you genuinely mean permanent removal — and confirm with the user before deleting.

So an agent’s power over Pages is authoring, discovery, and removal: list, read, validate, create, update, archive, and the scoped-and-confirmed hard delete. Only rendering stays with the host, off the agent path.

Authoring a Page from a blueprint

Amdahl ships a starter blueprint — viz_page_from_query— that packages this whole flow as a recipe. A blueprint is read-and-walk: the agent reads the recipe, then performs each step with its own tools. This one takes a plain-language question, plans the page shape, probes the tenant’s real data to ground the SQL, authors the spec, and calls pages.create — ending with a published Page. Read it over the agent_blueprint:// resource (or the blueprints tool) and walk the steps. It needs the same pages:write access as authoring a Page by hand, so it runs from an MCP client with a page-authoring key, not the in-app copilot.

The same operations over REST

Driving Pages from a script or backend service instead of an agent? The same lifecycle is on the REST API — create, validate, update, archive, hard-delete — plus the one REST-only action, render. See Authoring via the API.