An MCP server (Maket) that lets an AI assistant compose HTML/CSS print-and-screen documents with live preview, data binding, and export to PDF or Gmail drafts.
Documents – create, list, duplicate, rename, delete, edit metadata, and export/import portable .maket bundles.
Canvas – set paper (A2–A8) or screen formats, orientation, background, and per-side print margins.
Pages – add, remove, rename, reorder, and list pages in a document.
HTML content – full set, surgical patch by data-id, get, and layout check (overflow/overlap/margin) with charte-token compliance.
Brand chartes – create, view, list, and delete design-token style guides (colors, fonts, spacing).
Collections – define JSON Schema-typed row sets and bind a page to render one output page per row (mail merge).
Living documents – attach validated, revisioned document state with Mustache display and bound checkbox/text/select/button controls, plus history and restore.
Mermaid diagrams – render charte-aware inline SVG flowcharts, sequence, class, ER, state, and XY charts.
Image library – list, view, import (URL/path), tag with metadata, and delete assets.
Preview – open the live browser preview or snapshot a page as PNG.
PDF export – render all pages via headless Chromium at selectable DPI and collection-row modes.
Gmail – connect OAuth, search/read mail, fetch attachments, and create drafts from a document (never sends).
Workspace session – focus a doc/page, inspect state, lock a document, fit view, and read/ack user messages.
Agent guidance – maket_learn returns structured Markdown on workflow, HTML, chartes, diagrams, collections, state, review, and install.
Allows creating Gmail drafts from document pages, searching and reading messages, and fetching attachments. Supports OAuth authentication and draft-only or read access.
Adds diagrams (flowcharts, sequence, class, ER, state, XY charts) to document pages using Mermaid syntax, rendered as SVG with customizable themes and colors.
Create visual documents with your AI assistant. Maket gives Claude, Codex, Gemini, and other MCP clients an HTML/CSS canvas with live preview. Compose a one-off design, bind a template to typed rows for mail merge, or attach validated document-owned state so native HTML controls and agent updates keep a living document current. Export finished output to PDF or hand it off to Gmail as a draft.
Maket App is the default way to run Maket. It includes the interface, server, runtime, and agent setup — Node.js is not required.
Platform | Installer |
macOS Apple Silicon |
|
macOS Intel |
|
Windows x64 |
|
Linux x64 |
|
Download the newest snapshot
to test Maket App now. Snapshot installers are unsigned, built from main, and
retained for 14 days. The same unsigned installers for macOS and Windows, plus
Linux packages, appear on the
latest release.
Open the installer, launch Maket, then follow the first-run agent setup.
Need a headless server, CI installation, or browser-only deployment? Jump to Maket Server via npm.
Related MCP server: anno
Your AI assistant is good at writing. But design is about space, hierarchy, and rhythm — and that happens in layout, not prose. Maket adds a real canvas, reusable visual resources, and two distinct data models: collections produce repeated variants from ordered rows, while document state keeps one document synchronized with its own validated, revisioned data.
Live preview — Changes appear in your browser the instant the AI writes them. Use Annotate in the detail document toolbar (or connected Reader) to select an element and save feedback for the agent; turn it off to resume navigation.
HTML/CSS canvas — Pages are real HTML sized in mm. No lock-in to a proprietary format.
Brand chartes — Define design tokens (colors, fonts, spacing, shadows) once; Maket enforces them during composition.
Image library — Drop images in, tag them, the AI picks the right one for the brief.
Data-driven collections — Define typed fields with JSON Schema, paste or edit ordered rows, bind a page to placeholders such as {{ product_name }}, preview one row or the full series, and render one output page per row.
Living documents — Attach a JSON Schema and state snapshot to one document, render {{ state.* }} values, edit supported fields through bound checkbox, text, select, and button controls, and retain immutable revisions for history and restore.
PDF export — Print-ready output via headless Chromium.
Gmail drafts — Compose an email document and hand it off to Gmail as a draft; you review and send yourself.
Paper & screen formats — A2–A8, DESKTOP/TABLET/MOBILE aspect ratios, and AUTO pages with a defined width and content-driven height.
Agent skills included — Three skills (maket, maket-charte, maket-review) that teach the AI assistant how to design, brand, and review documents.
You — fais-moi un flyer A5 pour un concert jazz dimanche soir, ambiance feutrée
AI — maket_doc new doc="Jazz flyer" format=A5 orientation=portrait
maket_charte view name="Smoky Club"
maket_html set doc="Jazz flyer" page=1 context_token=...
→ Live preview opens. Warm amber on deep navy, serif display for
the headline, fine sans for the venue details.
You — (clicks the date on the preview) "rends-la plus grosse"
AI — maket_workspace list_messages → sees your note
maket_html patch doc="Jazz flyer" ops=[...]
→ Date scales up, hierarchy re-balanced.
You — parfait, exporte
AI — maket_pdf doc="Jazz flyer"
→ ~/.maket/exports/jazz-flyer.pdfCollections turn a page into a reusable template for product labels, event badges, personalized flyers, certificates, catalog pages, or any other repeated document. Each collection owns a JSON Schema and a set of ordered rows. Bind it to a page, place typed values in the HTML with {{ field_name }}, and Maket renders one variant per row.
The Collections workspace and maket_collection tool both support schema changes, row insertion/update/delete, paste-oriented tabular editing, and validation feedback. Maket validates the schema, every row, and every placeholder before rendering. In the preview you can keep the raw template visible, inspect one selected row, or display the complete generated series; print and PDF output expand the bound page across all rows.
You — crée une série d'étiquettes produit avec le nom et le prix
AI — maket_doc new doc="Product labels" format=A6 orientation=portrait
maket_collection action=create name=products
schema='{"type":"object","properties":{"product_name":{"type":"string"},"price":{"type":"string"}},"required":["product_name","price"]}'
maket_collection action=add_row name=products
data='{"product_name":"Earl Grey","price":"12 €"}'
maket_collection action=add_row name=products
data='{"product_name":"Sencha","price":"14 €"}'
maket_collection action=bind doc="Product labels" page=1 name=products
maket_html set doc="Product labels" page=1
html='<article data-id="label"><h1 data-id="name">{{ product_name }}</h1><p data-id="price">{{ price }}</p></article>'
→ The preview can show the template, either product, or both generated labels.
You — exporte toute la série
AI — maket_pdf doc="Product labels"
→ One PDF page per collection row.Document state is for a single evolving artifact: a checklist, status board, form, or report whose current values belong to that document. maket_state initializes a JSON Schema and data snapshot, validates every update, requires the current revision for mutations, and records each accepted change as a complete immutable revision. Updates re-render the existing pages; they do not create mail-merge variants.
A page can use HTML, JSON Forms, or HTML embedding its current JSON Forms template at <!--maket-json-form-->. A hand-authored HTML template uses the supported Mustache subset for display and explicit data-maket-bind attributes for editing. A JSON Forms template is set with maket_page action=set_form; its optional UI schema controls layout while the document-state JSON Schema supplies fields and choices. Maket renders both formats with native controls through the same state owner. The same current values render passively in snapshots, print, and PDF output.
For sequential questions, keep the subject and answer-history Mustache list in HTML, place exactly one <!--maket-json-form--> inside a static block container outside Mustache sections, and call maket_page action=set_form for each question. Changing the form preserves the HTML and document state. The embedded form adapts to its container.
JSON Forms styling is renderer-owned: attach a charte to apply its text, background, surface, border, accent, muted, and font tokens. The UI schema controls structure and presentation options, not arbitrary CSS.
<h1 data-id="title">{{ state.title }}</h1>
<label data-id="done-label">
<input data-id="done-input" type="checkbox" data-maket-bind="state.done">
Done
</label>
<input data-id="owner-input" type="text" data-maket-bind="state.owner">Use maket_state action=init to attach the initial schema and data, then get, patch or update, history, revision, and restore to manage it. Portable .maket bundles carry the current schema, data snapshot, and template format; importing one starts a fresh local history at revision 1 rather than copying prior revisions. See the document-state template contract for the exact template, schema, control, and concurrency rules.
A Structured Workspace groups one or more named collections whose detail views are real, persistent living documents. Its data schema validates every item and may use oneOf; its representation schema gives each collection a global template and binds concrete schema paths to compact and detail template documents. Every collection has its identity, a JSON Pointer to a required string or number property of its items, /id by default when the data schema requires an id property (so a Workspace is still created from a data schema alone); the value of that property, as a string, is the item id everywhere (documents, annotations, pins, cursors, MCP calls), unique across the whole Workspace, all collections included, and Maket never generates one. Adding an item without that value, or with a value another item of the Workspace already bears, is refused naming the field or the existing item; an update cannot change it, and the generated detail form shows it read-only. Adding an item stores its data at revision 1 and gives it the next value of its collection's insertion sequence, a stored counter that only grows and is never reused. A collection may declare sortBy (a JSON Pointer into the item data, such as /place) with sortDirection ascending or descending, and its index then orders the cards of each group by that value and equal values by item id, re-sorted whenever an item or the definition changes, while a collection without it keeps insertion order. Workspaces created before declared identities were migrated once: each collection without identity gained an id property holding the former item id (or itemId when an id property held other values), so documents, annotations and pins kept resolving; a Workspace read from a bundle written before identities gets the same declaration at import.
Items are served to the index, the workspace views and the MCP answers through a data source interface (ItemSource, in packages/server/src/services/item-sources/): it lists item summaries in index order with a cursor and a total, reads one item with its revision, and writes at an expected revision. Its first implementation is Maket's own storage, where each item is one row of structured_workspace_items holding its data and revision. The source holds the data and the document holds the rendering: an item's document is created only when the item is first opened, with an id derived from the Workspace and item ids and the name given at add_item, which stays reserved for it whether or not it was opened (maket_doc and the document commands refuse it); item documents are not loaded when Maket starts but on demand, and stay loaded once opened; an export creates the documents it lacks and removes them once the bundle is written; an item document stays out of the Documents library and document search, and its state is a mirror of the row, refreshed on open and after each write. A .maket bundle carries each Workspace definition with its item rows (identity, data, revision) and the item documents it holds rendered, never item data in document states; an import rebuilds the rows, and an export reports every item whose document it leaves out. The detail form, maket_state and update_item all write through the source at the row revision, so a stale write is refused with the current data. The item history is not kept in the document state. The list is read by cursor: a query (free text over the collection searchFields, by default every text property, ignoring case and accents, filters, sort and a batch size, indexPageSize 50 by default and at most 500) answers one batch with an opaque next cursor, the total and the item count of each group, pushed down to one SQLite query; a new query restarts from the first item and there is no page number. The cursor is the sort value and the item id under a sort, the insertion sequence and the item id otherwise: no item that existed before the first batch and kept its sort value is skipped or repeated, while an item whose sort value changes during paging may move across the cursor. check and update_definition read the items by batches through the source, and update_definition reports the first breaches of a new definition. The server holds the current window of each collection, shared by every client and the agent, and re-reads it when the source changes: the index document renders that window (the first batch, then each batch loaded after it) under group headers that count the whole query, the index pane offers a search bar and a load-more control, the client keeps only the window and light workspace views (item counts and pinned items, never the item data), and maket_structured_workspace action=view answers one batch of the window with its cursor.
An agent builds a Workspace along one of three paths, documented step by step in maket_learn action=topic topic=structured-workspaces: from a data schema alone, where Maket writes the index, detail and card templates and an edit form itself; with the template HTML and form given inline in the create call, where Maket still creates and names the template documents in the Workspace category; or by naming template documents created beforehand, which binding moves out of the Documents library. create and update_definition refuse a definition with errors, one line per error with its collection, path and fix, unless allow_incomplete is set, and maket_structured_workspace action=check returns a ready or not-ready verdict with every finding, its correction and the next call, without changing anything.
The Workspace sidebar lists collection indexes and pinned items only; other items are opened from their index, and templates remain available in the Workspace actions menu. The icon-only display toggle in the general toolbar switches between a single document (Square) and list/detail (PanelLeft); there is no separate view-choice toolbar. Opening another item replaces the current detail pane; closing the item returns to its index. Both panes open in Reader with ordinary scrolling; a narrow AUTO list holds the batches loaded so far on one continuous page, and its load-more control appends the next batch. Explicit Canvas navigation enables independent wheel zoom and drag pan, and the header percentage resets the fit. A draggable, keyboard-accessible separator starts at 28/72 and adjusts the widths. On narrow windows the library opens as an overlay, preserving readable document widths and its pin preference. Item pins persist and can be removed from the sidebar. This browsing surface keeps live document forms interactive; template authoring continues on the canvas.
Reader shows the focused document with titles above each page of a multi-page document. Entering Reader from collection browsing preserves the current page; switching between its open index and item keeps their navigation context. Closing Reader restores the originating document and page and the single/split layout. Passive page visibility in either split pane remembers its own position without taking focus from the other pane. Closing all documents cancels pending explicit openings, so late server replies cannot reopen the workspace.
Template-controlled pages stay synchronized across every existing item and index document and are edited at the template. Pages added to one instance remain editable and survive template synchronization. maket_structured_workspace exposes workspace creation, revision-checked schema and template-binding changes, item creation and mutation, deletion, inspection, and explicit template synchronization through MCP.
Pick the row that matches your machine.
Platform | Recommended | What you get |
macOS (Apple Silicon or Intel) | Maket App — | Native window, embedded server, agent setup on first launch |
Windows x64 | Maket App — | Same |
Linux x64 | Maket App — | Native window and embedded server; manual updates |
Download the installer from the latest release, using the filename for your platform:
macOS Apple Silicon — Maket-macOS-arm64.dmg
macOS Intel — Maket-macOS-x64.dmg
Windows x64 — Maket-Windows-x64-Setup.exe
Linux x64 — Maket-Linux-x64.deb or Maket-Linux-x64.rpm
On macOS, open the .dmg and drag Maket onto Applications. On Windows,
run the installer; it sets up the Start menu entry and a desktop shortcut. The
macOS and Windows installers are currently unsigned. On macOS, if Gatekeeper
blocks the first launch, Control-click Maket, choose Open, then confirm
once. Windows may show a SmartScreen warning that must be confirmed manually.
On Linux, install the package with your distribution's package manager; updates
are downloaded manually. For a version not yet released, use the Linux snapshot
artifact from the matching main commit. See Linux installation and sandbox diagnostics.
Maket App carries its own runtime — you do not need Node.js installed. On
first launch it offers to wire the AI clients it finds on your machine (Claude
Code, Codex, Gemini) to its embedded server, and it can install the bundled
connector for Claude Desktop. The embedded server listens on 127.0.0.1:24843.
If a Maket server is already running from a previous npm install, the application says so and offers to stop it and take over — nothing is killed without your confirmation.
The window is not the only way in: the Maket menu has Ouvrir dans le
navigateur, which serves the same workspace at http://127.0.0.1:24843 in any
browser on that machine. Only that machine — the server never binds a public
interface, so nothing is exposed to your network.
Updates are checked automatically and installed on your confirmation. The Candidate channel in Settings opts you into validation builds.
# Install Maket and its compatible headless Chromium
npm install -g --allow-scripts=puppeteer @ng-galien/maket
# Wire Maket into your AI client (drop --apply for a dry run)
maket install claude --apply
maket install codex --apply
maket install gemini --apply
# Start the local server and open the preview
maket start
maket openIn Chrome, Edge, or another supporting browser, use Install Maket in the
browser UI or in Maket Settings to keep the workspace in its own application
window. This PWA uses the same local server: it does not start, stop, or update
the native process, so maket start, maket stop, and maket update remain
explicit terminal commands.
The explicit --allow-scripts=puppeteer is required by npm 11+'s dependency
script policy. It lets Puppeteer download the exact headless Chromium build
declared by the installed Maket release; no browser version is hard-coded by
Maket itself. Run maket doctor after installation to prove that Chromium can
actually launch, the data directory is writable, and the MCP server responds.
The CLI registers the absolute local Node runtime and installed Maket entry in an mcpServers.maket entry in ~/.claude.json (or runs claude mcp add if the Claude Code CLI is installed), a [mcp_servers.maket] section in ~/.codex/config.toml, or an mcpServers.maket entry in ~/.gemini/settings.json. This standard command-plus-arguments form does not depend on the GUI application's shell PATH. Re-run maket install <client> --apply after moving the Node or Maket installation. Without arguments, the Maket entry runs as a stdio MCP bridge — that's the form Claude Desktop, Codex, Gemini, and other MCP clients invoke automatically.
Daemon controls: maket status, maket logs [--bridge], maket stop, maket restart. Diagnostics: maket doctor, maket config. Upgrade: maket update [--check]. Undo install: maket uninstall <claude|codex|gemini> --apply. Use --scope=project on install claude to write <cwd>/.mcp.json instead of the user-scope file. Global flags --data-dir, --port, --host override the matching MAKET_* env var on any command.
git clone https://github.com/ng-galien/maket.git
cd maket
npm install
npm run devStarts the development server on :24844 and Vite HMR on :5173. The included .mcp.json points an MCP client opened in the project at http://localhost:24844/mcp. Port :24843 is reserved for the installed desktop application.
Maket uses code-moniker for structural rules and code-smell review. The versioned rule source is .code-moniker.toml; run npm run smell:rules to inspect the default rules and npm run smell:review to review the repository. The quality gate runs this review through npm run quality.
Do not add enforceable architecture or boundary rules to AGENTS.md, and do not add ad-hoc checker scripts in parallel with code-moniker. AGENTS.md is operator guidance for agents working in the repository; it is not the project's rule engine. If a boundary rule cannot be expressed with code-moniker yet, document that as a code-moniker evolution instead of creating another local rule system.
Exceptions are local and explicit. If a rule is intentionally not applicable, keep the rule enabled and add a targeted suppression comment in the file being checked, for example // code-moniker: ignore[maket-hygiene-limits-callable-size], with a nearby explanation of the design reason.
npm install -g @anthropic-ai/mcpb
npm run build:client
node scripts/pack-mcpb.ts
# → dist/maket.mcpbDrag dist/maket.mcpb into a desktop MCP host (e.g. Claude Desktop → Settings → Extensions).
Requirements: an MCP-compatible client (Claude Code, Claude Desktop, Codex,
Gemini, or similar). Maket App bundles everything else; the npm, clone and
.mcpb routes additionally need Node.js ≥22.
maket [command] [--data-dir <path>] [--port <n>] [--host <h>]
bridge Run the MCP v2 stdio gateway (default for MCP clients)
start Start the Maket HTTP server in the background
stop Stop a server started by 'maket start'
restart Stop (if running) then start
status Show whether the server is reachable
open Open the Maket UI in your browser
logs [--bridge] Tail server (or bridge) logs
config Print the resolved runtime config
doctor One-shot diagnostic (node, port, data dir, Chromium, Gmail, npm)
update [<version>] Upgrade the CLI (or pin to <version>); --check for a no-op compare
install <client> Wire Maket into an MCP client (claude | codex | gemini)
uninstall <client> Remove Maket from an MCP client (claude | codex | gemini)
install/uninstall flags: --apply, --scope=user|project
gmail <sub> Manage Gmail OAuth state (status | reset [--force])
help, versionMaket exposes 15 compound MCP tools. Each one dispatches multiple actions:
Tool | What it does |
| Document lifecycle — new, list, delete, duplicate, rename, meta, export/import |
| Structured Markdown documentation for agents — workflow, HTML, chartes, diagrams, data, review, install |
| Session actions — focus, state, lock, list_messages, ack_messages |
| Page structure and JSON Forms templates — add, remove, rename, reorder, list, set_form, get_form |
| Canvas setup — format, orientation, background, per-side print margins |
| Page content — |
| Brand chartes — list, view, set, delete |
| Typed data collections — list, view, create, validate/change schema, add/update/delete rows, bind/unbind a page |
| Document-owned state — initialize, get, update or JSON Patch, validate/change schema, inspect history and revisions, restore |
| Schema-driven item collections — create (templates generated from the schema or given inline, identity declared per collection), check, read items by cursor, add/update/delete items, synchronize template pages |
| Asset library — list, view, meta, import, delete |
| Open the live preview URL or snapshot a page to PNG |
| Render a durable, charte-aware Mermaid diagram with semantic tokens and safe visual controls |
| Export a document to PDF via headless Chromium |
| Gmail — connect, search, read, draft |
Layout & print margins guide: docs/layout.md — what the cyan safe-zone in the preview means, margin presets per use case, and prompts to ask the assistant when something looks off.
The MCP server exposes maket_learn, the source of truth for agent onboarding. Skills stay thin: they orient Claude, Codex, or Gemini toward the live tool guidance instead of duplicating product knowledge. Human onboarding is separate and opens from the Help button in the Maket UI.
The plugin/claude/ directory ships three agent skills:
maket — Orientation skill. Starts with maket_learn, then uses the MCP tools for design work.
maket-charte — Brand-identity expert. Builds coherent design-token systems from a brief, an industry, or a reference URL.
maket-review — QA agent. Audits charte compliance, image paths, layout overflow; fixes issues via maket_html patch.
Claude, Codex, and Gemini compatibility files live under plugin/.
By default Maket stores data in ~/.maket/:
documents.db — SQLite (documents, chartes, collections, assets metadata)
assets/, documents/, exports/ — user files
Override with environment variables:
Variable | Default | Purpose |
|
| HTTP server port |
|
| User data directory |
|
| SQLite path |
| — | Gmail OAuth credentials (optional) |
Maket can turn a composed document into a Gmail draft (with PDF attachments). It only creates drafts — never sends. You review the draft in Gmail and click Send yourself.
Setup takes about 10 minutes: you register your own OAuth Desktop client in Google Cloud Console, enable the Gmail API, add yourself as a test user, and paste the JSON into Maket's setup form. Credentials live under ~/.maket/ with owner-only permissions — nothing in the repo, nothing on any server.
Full walkthrough + troubleshooting: docs/gmail-setup.md.
Quick CLI helpers once set up:
maket gmail status # check whether credentials are in place
maket gmail reset --force # wipe and start overIf you run Maket as a long-lived server and want other projects to connect to it:
make bootstrap DIR=/path/to/my-project PORT=3335Creates .mcp.json, .claude/skills/, and a minimal package.json in the target directory. Never overwrites existing files.
┌──────────┐ MCP Streamable HTTP ┌────────────────────────┐
│ AI agent │ ──────────────────────► │ Express @ :3333 │
│ (any │ │ ├─ /mcp (MCP server) │
│ MCP │ │ ├─ /assets, /export │
│ client) │ │ └─ WS /ws (preview) │
└──────────┘ └────────┬───────────────┘
│
┌────────┴────────┐
│ SQLite │
│ ~/.maket/*.db │
└─────────────────┘
│
▼ WS broadcast
┌─────────────────┐
│ React preview │
│ (Vite, :5173) │
└─────────────────┘MCP over Streamable HTTP — stateless, one server per request.
Awilix DI — every service, tool pack, and HTTP route is registered in packages/server/src/bootstrap.ts.
Store → bus → WebSocket — every mutation emits a typed event; the preview reconciles.
packages/shared — wire-contract types only (WS messages, HTTP envelopes). Domain types stay per-side.
See CLAUDE.md for the full architectural guide.
npm run dev # Server + Vite HMR (most common)
npm run quality # Lint + typecheck + tests (must pass before commit)
npm run test # vitestPre-commit: lefthook runs biome, tsc -b, and vitest — all three must pass.
More scripts: dev:watch (rebuilds client into public/), dev:server, dev:client, build:client, lint:fix, test:coverage. See package.json for the full list.
Contributions are welcome. To get started:
Fork the repo and create a feature branch.
Run npm install && npm run dev to set up your environment.
Make your changes; keep them scoped (a bug fix doesn't need surrounding cleanup).
Run npm run quality — it must pass.
Open a PR with a clear description of the change and motivation.
Found a bug, have an idea, or want to discuss something before building it? Open an issue or start a discussion.
See CHANGELOG.md for user-visible changes per release. Draft the next [Unreleased] section with npm run changelog:draft (groups commits since the last tag by conventional-commit type).
Agent journal — Field notes from the agents working on Maket.
MIT — © Alexandre Boyer
When to use: set or update the canvas (physical frame) of a document — format, orientation, background, margins. Call this before adding content to a fresh doc, or when switching a doc between formats.
Coordinates are in mm. Paper sizes — A2=420×594, A3=297×420, A4=210×297, A5=148×210, A6=105×148, A7=74×105, A8=52×74. Screen sizes — DESKTOP=288×205 (1440×1024), TABLET=167×239 (834×1194), MOBILE=79×170 (393×852). AUTO — width in mm is required; each page height follows its content. Orientation is ignored. Use normal HTML flow rather than a fixed-height wrapper. Unspecified fields keep their current value.
| Name | Required | Description | Default |
|---|---|---|---|
| doc | Yes | Document name. | |
| width | No | Width in millimetres for AUTO format; required on creation. Height follows each page content. | |
| format | No | Paper (A2–A8, mm) or screen (DESKTOP/TABLET/MOBILE, mm-equivalent). Unspecified keeps the current value. | |
| margins | No | Per-side safe-zone insets in mm: {top, right, bottom, left}. The layout verdict reports `tight` when blocks cross into any band, and the client draws dashed guides at these insets. Unspecified keeps the current value. | |
| background | No | CSS background colour. Unspecified keeps the current value. Prefer var(--charte-color-bg) when a charte is loaded. | |
| orientation | No | Page orientation. Unspecified keeps the current value. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does well: it states that unspecified fields retain current values (partial-update semantics), that AUTO only requires width, and that orientation is ignored in AUTO mode and normal HTML flow should be used. It omits permission/auth requirements and what happens on a nonexistent or locked document.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the when-to-use condition, then reference data in compact labeled lists. The size tables are dense but genuinely reference material an agent needs; slightly list-heavy formatting keeps it from a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-param mutating tool with a nested margins object, no annotations, and no output schema, the description covers units, defaults retention, and enum semantics well. It could still say more about failure modes or whether the canvas can be created implicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so baseline is 3; the description earns a bump by supplying the actual paper and screen dimensions (A2=420×594 … MOBILE=79×170) and the AUTO width/orientation interaction, information the schema's enum does not carry. Remaining params (margins, background) mostly restate the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource: 'set or update the canvas (physical frame) of a document', then enumerates the four attributes it governs (format, orientation, background, margins). The 'physical frame' framing cleanly separates it from content-oriented siblings like maket_page, maket_html, and maket_doc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'When to use' plus two concrete triggers: before adding content to a fresh doc, or when switching formats. No alternatives or when-not guidance is offered, so it stops short of the top band.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
When to use: manage brand style guides (chartes). view is a prerequisite for any charte-aware HTML edit — it returns the context_token required by maket_html set/patch.
Design tokens become CSS variables (--charte-color-primary, etc.) injected into every page. Voice and rules guide content composition. maket_mermaid automatically consumes canonical diagram tokens and documented fallbacks from color/font groups; its tokenRefs option can target any existing safe token explicitly. list — list all chartes with a short colour-palette preview. view — read one charte; returns tokens, voice, rules, and context_token. set — create or overwrite a charte. delete — remove a charte.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Required for view/set/delete. Unique charte name. | |
| rules | No | For set: composition rules (titles, photos, layout). Extra keys allowed. | |
| voice | No | For set: voice guidelines (personality, formality, do/dont, vocabulary, examples). | |
| action | Yes | Operation to run. See the tool description for the action table. | |
| tokens | No | For set: design tokens grouped by category. Become CSS variables --charte-<group>-<key>. Diagram roles can use a canonical "diagram" group (bg, fg, line, accent, muted, surface, border, font, padding, nodeSpacing, layerSpacing, transparent). Example: {"color":{"primary":"#2563EB"},"font":{"body":"Montserrat"},"diagram":{"surface":"#EFF6FF","nodeSpacing":"32px"}}. | |
| description | No | For set: one-line human description. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It explicitly states that tokens become CSS variables injected into every page, that set creates or overwrites, and that delete removes a charte. It does not discuss irreversibility or permissions, but the main behavioral traits and outputs are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a 'When to use' lead and then builds toward a compact action table. The prose sentences about CSS variables and maket_mermaid are relevant context, and the action list gives a crisp overview. It is slightly longer than the minimum needed, but every section earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all four actions, explicitly states what view returns (tokens, voice, rules, context_token), and explains the cross-tool dependency on context_token. The schema covers parameter formatting in detail. Minor gaps such as error conditions or permission requirements exist, but the essential invocation context is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all parameters with 100% schema description coverage, so a baseline of 3 is appropriate. The description adds context about tokens becoming CSS variables and view returning a context_token, but it does not add much parameter-level syntax beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's resource ('brand style guides (chartes)') and enumerates four concrete operations: list, view, set, and delete, each with a one-line outcome. This distinguishes it from sibling tools like maket_html and maket_mermaid by naming exactly what it manages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description opens with 'When to use' and explicitly explains that view is a prerequisite for charte-aware HTML edits because it returns the context_token needed by maket_html set/patch. It also provides cross-tool context for maket_mermaid. It lacks explicit when-not-to-use or alternative-selection rules, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
When to use: manage data collections used by page placeholders.
Collections are typed by JSON Schema and contain ordered members. A page can be bound to one collection; rendering then produces one page per member. list — list collections. view — read one collection with fields and members. create — create an empty collection from a JSON Schema. validate_schema — check a schema against existing members without saving. change_schema — apply a schema only when existing members validate. add_row / update_row / delete_row — edit collection members. delete — remove a collection. bind / unbind — bind or clear a collection on a document page. cursor — read or move a bound page's preview cursor (doc + page required). Without mode/row it reads; with mode (template|rendered|all) and/or row (member id or 1-based number) it moves. The human's live canvas, this cursor and the exports all share this state.
| Name | Required | Description | Default |
|---|---|---|---|
| doc | No | ||
| row | No | ||
| data | No | ||
| mode | No | ||
| name | No | ||
| page | No | ||
| action | Yes | ||
| schema | No | ||
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that collections are typed by JSON Schema, contain ordered members, and that rendering produces one page per member. It also explains cursor behavior and state sharing ('The human's live canvas, this cursor and the exports all share this state') and validation behavior for change_schema. It does not cover side effects of delete or all actions, but provides meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a 'When to use' intro and a bulleted list of actions. The cursor explanation is somewhat lengthy but necessary. Overall, it is organized and front-loaded, with little wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex (9 parameters, many actions) with no output schema and no annotations. The description gives a comprehensive overview of all actions and even notes parameter requirements for cursor, but it lacks per-action parameter details (e.g., which parameters are needed for 'create' or 'bind') and does not describe return values or outputs. This leaves gaps for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does explain the semantics of the action enum values (e.g., 'cursor — read or move a bound page's preview cursor' and specifically notes 'doc + page required'). However, it does not describe other parameters like 'data', 'name', 'schema', or 'description' in detail, leaving some parameters underspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'manage data collections used by page placeholders,' providing a specific verb and resource. The list of actions (list, view, create, etc.) clearly distinguishes this tool from siblings like maket_page and maket_canvas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The explicit 'When to use' heading and the description of collections (typed by JSON Schema, ordered members, page binding) give clear context for when this tool applies. It does not mention when not to use it or alternative tools, but the specificity of page placeholders makes the usage context unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
When to use: every persistent document-lifecycle operation — create, clone, rename, delete, list, update metadata, or move bundles in/out. For session-level actions (open a doc/page in the preview, inspect state, lock), use maket_workspace. For per-page edits use maket_page and for content use maket_html.
doc is the doc in scope for every action except list. name only appears when you need a NEW name (duplicate, rename).
Manage design documents (the workspace unit: canvas + pages + meta).
new — create a blank document at doc; sets it active. Previous unsaved work is lost.
list — enumerate saved documents: pinned documents first (most recently pinned first, marked 📌, with their category), then the other documents as a hierarchy of category paths.
lookup — read-only identity of doc by exact name, Workspace documents included: JSON {name, id, revision (monotonic modification token), pageCount, dataModel, stateRevision (null without state)}. It never opens the preview nor changes the active document. When absent, the error lists near matches.
link — return a reading path for doc, using its stable document id and configured browser base path. Prefix it with the reachable gateway origin.
delete — remove doc permanently; refused if it's the only document left.
duplicate — clone doc → name (format variants, A/B copies).
rename — rename doc → name.
meta — update doc's metadata: designNotes, teamNotes, rating, category, charte, responsive. The responsive flag applies to every browser-reader page while canvas/PDF keep authored dimensions. Owned Workspace templates accept responsive alone; sync_template propagates it.
pin — pin doc at the top of the document lists (desktop library, Reader navigation, list). The most recently pinned document comes first; pinning an already pinned doc keeps its place. Allowed on locked documents. Workspace item pins appear under their collection in the Workspace sidebar; indexes and templates cannot be pinned.
unpin — remove doc's pin; free documents return to their category and Workspace items disappear from the pinned shortcuts.
export — write a portable .maket bundle to EXPORTS_DIR. By default the bundle embeds referenced asset binaries (images, SVGs) so it survives transfer to another machine or a fresh datadir. Pass include_assets=false for a lighter structure-only snapshot. Include doc for a single document, docs for a list, or omit both to export every document. Referenced chartes, collections, and current document-state snapshots (with their revision retention) are embedded automatically; revision history stays local. Override the filename with output.
import — load a .maket bundle from input (absolute path or EXPORTS_DIR-relative). Documents land with conflict-renamed names; chartes and collections skip names that already exist. Current document-state snapshots initialize revision 1, and assets are restored to ASSETS_DIR with the existing collision rule.
| Name | Required | Description | Default |
|---|---|---|---|
| doc | No | The doc in scope. Required for every action except list. For lookup: the exact name to read. For new: the new doc's name (must be unique). For delete/meta/pin/unpin: the doc to act on. For duplicate/rename: the source doc. | |
| docs | No | For export: list of doc names to include in the bundle. Omit to export all documents. Ignored by other actions. | |
| name | No | The new name. Only used by duplicate (clone's name) and rename (new name). | |
| input | No | For import: absolute or EXPORTS_DIR-relative path to a .maket file to load. | |
| width | No | Width in millimetres for AUTO format; required on creation. Height follows each page content. | |
| action | Yes | Operation to run. See the tool description for the action table. | |
| charte | No | For new/meta: name of an existing charte to associate with this document. The charte itself is applied later via maket_charte view. | |
| format | No | For new: paper/screen format, or AUTO with width in mm and automatic page height. Default A3. Paper sizes are mm; DESKTOP/TABLET/MOBILE are screen aspect ratios scaled to mm. | |
| output | No | For export: output filename (defaults to <doc>.maket or maket-bundle.maket). Absolute paths are honoured; bare names land in EXPORTS_DIR. | |
| rating | No | For meta: 0–5 star rating (clamped). | |
| margins | No | For new: per-side safe-zone insets in mm {top, right, bottom, left}. Optional. | |
| category | No | For new/meta: category path separated by / (for example clients/acme). Flat values remain valid roots; default general. | |
| teamNotes | No | For meta: team-facing notes (visible in the UI). | |
| background | No | For new: canvas background colour (CSS). Default #ffffff. | |
| responsive | No | For new/meta: opt this entire document into fluid browser reading at its available pane width. Default false; canvas authoring and PDF keep their physical dimensions. On a Workspace template only this field may be changed through meta; then sync_template propagates it to projections. | |
| designNotes | No | For meta: designer-facing notes (visible in the UI). | |
| orientation | No | For new: page orientation. Default portrait. | |
| include_assets | No | For export: embed referenced asset binaries (images, SVGs) in the bundle. Default true — produces a portable .maket that survives transfer to another machine or datadir. Set false for a structure-only snapshot (smaller, git-friendly). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, and it does: 'new' warns that previous unsaved work is lost, delete is 'refused if it's the only document left', lookup is read-only and never opens preview or changes the active document, pin is allowed on locked documents while indexes/templates cannot be pinned, and export/import disclose asset embedding defaults, conflict-renaming, and revision-retention behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads when-to-use, then parameter scoping, then a punctuation-prefixed action table. Given 12 actions and a rich export/import surface, the length is largely justified, though a few entries (pin/unpin) carry more UI-context detail than an agent strictly needs to invoke the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 18-parameter, 12-action dispatcher with no output schema and no annotations, the description covers action semantics, destructive side effects, per-action return shape for lookup, and bundle-format rules for export/import. Nothing material an agent needs before invoking is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, but the description adds the cross-action scoping rule ('`doc` is the doc in scope for every action except list; `name` only appears when you need a NEW name'), which the per-parameter schema blurbs spread out rather than frame globally. It stops short of adding format/syntax detail beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb set and resource (persistent document-lifecycle operations on design documents), and enumerates all 12 actions with concrete semantics. It explicitly distinguishes itself from siblings: maket_workspace for session-level actions, maket_page for per-page edits, maket_html for content. An agent can route correctly without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Opens with an explicit when-to-use statement ('every persistent document-lifecycle operation') followed by when-not and which alternative to use instead ('For session-level actions... use maket_workspace', 'for per-page edits use maket_page and for content use maket_html'). Also adds intra-tool guidance such as '`name` only appears when you need a NEW name'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
When to use: connect Gmail, search/read mail, download an attachment, or create a draft from a Maket document. All actions except connect require an active OAuth session — call connect first.
connect — restore the refresh token if present, otherwise open the browser for OAuth consent. Pass with_read=true to also request inbox access (drafts are always granted). search — list subject/from/date for messages matching a Gmail query. Capped at 50. Requires with_read=true at connect time. read — fetch one message by id: headers, body (3000-char truncated), attachments listing. Requires with_read=true at connect time. fetch_attachment — download one attachment (id + attachmentId from a prior read). Images land in the Maket asset library (validated, optimized, thumbnailed, metadata row). Other files (PDF, zip, docx, …) drop into <DATA_DIR>/attachments/ untouched. Requires with_read=true at connect time. draft — compose a Gmail draft from a document page. Charte tokens resolve to literals, assets inline as base64, listed docs attach as PDFs. Maket never sends — the user reviews and sends from Gmail.
| Name | Required | Description | Default |
|---|---|---|---|
| cc | No | For draft: cc. Falls back to doc.meta.emailCc. | |
| id | No | For read: Gmail message id (from search results). | |
| to | No | For draft: recipient. Falls back to doc.meta.emailTo when omitted. | |
| bcc | No | For draft: bcc. Falls back to doc.meta.emailBcc. | |
| doc | No | For draft: Maket document to use as the email body. | |
| page | No | For draft: 1-based page number within the document. | |
| query | No | For search: Gmail query (same syntax as the UI: from:, subject:, after:, etc.). | |
| action | Yes | Operation to run. See the tool description for the action table. | |
| quality | No | For draft: PDF quality preset for attachments. Default screen (smaller). | |
| subject | No | For draft: subject. Falls back to doc.meta.emailSubject. | |
| category | No | For fetch_attachment (image branch only): category tag saved with the asset row. Default email-attachment. | |
| filename | No | For fetch_attachment: override the saved filename. Defaults to the name reported by Gmail. | |
| overwrite | No | For fetch_attachment: replace an existing file (asset or non-image drop) when set. Default false. | |
| with_read | No | For connect: also request read access (inbox search + message read). Default false — Maket only creates drafts. | |
| maxResults | No | For search: cap on results. Default 10, max 50. | |
| attachments | No | For draft: names of other Maket docs to attach as PDFs. Falls back to doc.meta.emailAttachments. | |
| attachmentId | No | For fetch_attachment: Gmail attachment id from a previous action=read call. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full disclosure burden and does an excellent job. It reveals OAuth flow, token restoration, read-body truncation to 3000 chars, search cap of 50, image handling (validated/optimized/thumbnailed/metadata row) vs non-image handling (untouched in <DATA_DIR>/attachments), and the 'never sends' policy for drafts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence 'When to use' summary followed by a compact action table. Every sentence earns its place; there is no fluff or repetition. The action-table format makes the multi-action tool easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description explains what each action returns (search lists subject/from/date, read returns headers/truncated body/attachments listing) and where files land. It covers prerequisites, side effects, and limitations (capped results, truncated body), making the tool fully comprehensible.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema already has 100% parameter coverage, the description adds cross-action context and fallback semantics (e.g., to falls back to doc.meta.emailTo, with_read defaults to false, fetch_attachment requires a prior read call). It also clarifies which parameters apply to which action, making it far more useful than schema descriptions alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific 'When to use' statement listing exactly the operations (connect Gmail, search/read mail, download attachments, create drafts). Each action in the table has a clear verb+resource (connect, search, read, fetch_attachment, draft), distinguishing it from sibling tools like maket_pdf or maket_preview.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool and prerequisites: 'All actions except connect require an active OAuth session — call connect first.' Each action is described with its specific conditions (e.g., 'Requires with_read=true at connect time'), and the draft action clarifies that Maket never sends, so the user reviews and sends from Gmail.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
When to use: read and write page HTML. Pick set for the initial skeleton, patch for iterative edits, get to read, check to measure overflow without writing.
Every visible element MUST have a data-id. Use flex/grid with mm units. When a charte is loaded, prefer var(--charte-*) tokens. The compliance check is narrow: it rejects (1) hardcoded colour literals that duplicate an existing charte token value (e.g. #2563EB when primary=#2563EB), (2) any hardcoded font-family when the charte defines fonts, (3) any hardcoded box-shadow when the charte defines shadows. Fresh colours that don't duplicate a token pass untouched.
Layout override: data-maket-layout="ignore" excludes exactly one marked non-interactive leaf block from overflow, overlap, clipping, and margin checks. The block must have no child elements or text; controls, links, data-maket-bind and focusable/ARIA elements are ineligible. Reserve it for intentional non-content decoration after visual review. Add it only with maket_html action=patch using attr on an existing data-id; the enabling op must be the only op in that patch request. Set, insert, replace, and content HTML cannot introduce it.
For a state-backed document, Mustache is display-only. The document must author editable controls and all their CSS explicitly: data-maket-bind supports for booleans, and for strings, for string enums (or for a string whose options come from a state list with data-maket-options="state.list"), and for the single-value editor; a bound button with data-maket-value="" (optionally data-maket-action="set") writes that value on click instead. Use state.foo at the root and relative foo inside state sections; never persist data-maket-path or other runtime attributes.
set — REPLACE the full page HTML. Rejects the whole payload on any violation. Requires context_token when the doc has a charte.
patch — apply ops by data-id: style/content/attr/insert/replace/remove/clone/moveTo. Violating ops roll back individually, the rest still apply.
get — return current HTML; pass id= for a single element, format=text to strip tags.
check — measure layout against the canvas + declared canvas.margins, and report page links that target a missing page; no side effects. The page is measured as readers see it: a state-backed page hydrated with the current document state (a JSON Forms page on its rendered form), a collection page with the member its preview cursor shows (first member otherwise), a Structured Workspace collection document with its items; a list that flows onto continuation pages is measured page by page; other pages as authored. The report's first line names what was measured. set and patch measure the same way. Returns a Markdown measurement report with physical canvas and content extents, root geometry, problematic addressable blocks, parent/canvas excess per side, clipping, and overlap pairs. Status: ✓ OK, ⚠ tight (block crosses a declared margin band — tighten or move into the safe zone before shipping), ⛔ overflow (block escapes the canvas, not shippable; pairwise overlaps between [data-id] blocks are reported under this same status), or ⛔ unchecked when headless validation could not run. On tight/overflow, the next: block points to a snapshot + targeted patch; unchecked is diagnostic-only to avoid blind retry loops.
Page links: (canonical, 1-based page number) or navigates to that page of the same document in Canvas, Reader and viewer, and becomes an internal link in print and PDF. In the authoring Canvas a plain click selects the link for editing; ⌘-click (Ctrl-click elsewhere) follows it. The href is a literal: set and patch refuse Mustache in a page link.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | For get: data-id of a single element to return; omit to fetch the whole page. | |
| doc | Yes | Document name (always required). | |
| ops | No | For patch: list of surgical ops by data-id. Each op has `id` plus one of: style (object), content (string), attr (object), insert (html) + optional position, replace (outerHTML), remove (true), clone (newId), moveTo (targetId) + optional position. To exclude one intentional non-interactive leaf decoration with no child elements or text from layout validation, patch that existing element with attr: {"data-maket-layout":"ignore"}; controls, links, data-maket-bind and focusable/ARIA elements are ineligible. This override is rejected in set/insert/replace/content HTML, and its enabling op must be the only op in the patch request. | |
| html | No | For set: full page HTML. Every visible element MUST carry a data-id. Use flex/grid with mm units; images use relative filenames (src="photo.jpg"); colours/fonts come from var(--charte-*). Example: <div data-id="page" style="width:210mm;height:297mm;display:flex;flex-direction:column;padding:15mm"><h1 data-id="title">Hello</h1></div>. | |
| page | Yes | Page number, 1-based (always required). | |
| action | Yes | Operation to run. See the tool description for the action table. | |
| format | No | For get: 'html' (default, full markup) or 'text' (tags stripped). | |
| context_token | No | For set: charte context token from maket_charte view. REQUIRED when the document has a charte — proof the brand guidelines were read first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so: it discloses set's all-or-nothing rejection, patch's per-op rollback, the context_token prerequisite for charte documents, check's lack of side effects and its exact measurement model (which state/pagination variant is rendered), and the meaning of each status symbol. This is materially richer than any annotation could express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The 'When to use' routing is front-loaded and every section is information-dense, but the data-maket-layout override rules (eligibility, single-op requirement, where it is rejected) are duplicated almost verbatim in the ops schema description, and the state-binding paragraph is lengthy. For a tool this complex the length is defensible, yet the duplication is avoidable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description compensates by describing what get returns (current HTML, or stripped text) and what check returns (a Markdown measurement report, first line naming what was measured). Given the tool's complexity, an agent has enough to author correct HTML and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real semantics beyond the schema: it constrains the ops shapes (e.g. attr for the layout override must be the only op; set/insert/replace/content cannot introduce it), explains that page links must be literal and reject Mustache in set/patch, and clarifies get's id/format behavior. It does not restate the schema verbatim, it extends it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first line states the verb and resource ('read and write page HTML') and immediately maps each of the four actions (set/patch/get/check) to a distinct job. An agent can tell which action to invoke without opening the schema, and the tool is clearly differentiated from siblings like maket_page or maket_canvas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use routing is provided ('Pick set for the initial skeleton, patch for iterative edits, get to read, check to measure overflow without writing'), plus rules on when to use the layout override versus not, and how to handle a state-backed document. Both positive selection criteria and exclusions/eligibility constraints are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
When to use: manage the asset library (images). view → meta is a required two-step: meta refuses any write without the context_token from the latest view call — proof the image was read before metadata is attributed.
Images live on disk under the assets dir; metadata lives in the store; both move together. list — list assets grouped by category; flags items missing metadata. view — load an asset inline (text + binary image) and return its context_token. MUST be called before meta. meta — write/update metadata; rejects without a current context_token. import — copy an asset in via url, path, or register-mode (filename-only for already-present files). Auto-optimises + thumbnails. delete — remove the file, thumbnail, and metadata row.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | For import: HTTP(S) URL to download from. | |
| path | No | For import: local filesystem path to copy from. | |
| tags | No | For meta/import: searchable tags. | |
| title | No | For meta/import: human title. | |
| action | Yes | Operation to run. See the tool description for the action table. | |
| credit | No | For meta/import: attribution / photographer credit. | |
| category | No | For list: filter to this category. For meta/import: category tag. | |
| filename | No | Asset filename. Required for view/meta/delete. For import: destination filename (required in register-mode, derived from url/path otherwise). | |
| overwrite | No | For import: overwrite an existing file with the same name. | |
| description | No | For meta/import: long prose. | |
| orientation | No | For meta/import: orientation hint (landscape/portrait/square). | |
| context_token | No | For meta (REQUIRED): token returned by the matching view call. Proves the image was read before its metadata is written. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full disclosure burden. It reveals disk storage, metadata store, combined movement, delete side effects (removes file, thumbnail, and metadata row), and the auto-optimisation/thumbnail behavior on import. It also discloses the authorization mechanism (context_token rejection). This is thorough behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense yet perfectly scoped: a one-sentence overview, a two-step workflow explanation, and a compact bulleted action list. Every sentence adds distinct value—no filler or repetition. The structure is scannable and front-loaded with the most critical constraint (the two-step rule).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 12 parameters and 5 operations, the description covers all actions, the critical ordering constraint, storage model, and side effects. It mentions some return behavior (context_token, listing flags). However, without an output schema, it omits details about error conditions and full response formats, which would improve completeness for an agent deciding to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and every parameter already has a detailed schema description. The tool description adds a high-level action table but no parameter-level detail beyond what the schema provides. Baseline 3 is appropriate because the schema does the heavy lifting; the description does not meaningfully compensate but also doesn't need to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'manage the asset library (images)'—a specific verb and resource that clearly distinguishes this tool from sibling content tools. It then enumerates the five sub-actions (list, view, meta, import, delete) with concise definitions, making the tool's scope unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states the required two-step sequence for metadata writes: 'view → meta is a required two-step' and 'MUST be called before meta.' It also explains why (context_token proves the image was read). While it doesn't name sibling tools as alternatives, the asset-library scope and action table give unambiguous when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
When to use: first call for any agent entering Maket; source of operational guidance for using Maket MCP tools correctly.
Returns structured Markdown inside MCP text content. It teaches agents how to operate Maket: workflow, HTML composition, chartes, diagram styling, collections, living document state, Structured Workspaces, review loop, and client installation. This is not the user-facing Help document opened from the Maket UI.
Actions: overview — short operating model. topics — list available topics. topic — read one topic with topic=.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | Required for action=topic. | |
| action | No | Default: overview. | |
| audience | No | Default: agent. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose the return medium ('structured Markdown inside MCP text content') and enumerates the operational areas covered (workflow, HTML composition, chartes, collections, review loop, install, etc.). It also clarifies it is not the UI Help document. It does not state read-only status, permissions, or side effects, so it stops short of full behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the 'When to use' guidance, then the return format, then a compact action list. The middle paragraph is dense but each clause names a distinct operational area an agent needs to know is covered; only the 'not the user-facing Help document' aside is arguably marginal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description must cover return values and behavior, and it does (Markdown in MCP text content, per-topic scope). The audience parameter's semantics are left to the schema, and nothing tells the agent how large or expensive the returned topics are, but for a zero-required-parameter guidance tool this is close to complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with enum descriptions, so the baseline is 3. The description goes beyond the schema by explaining the semantics of each action ('overview — short operating model', 'topics — list available topics', 'topic — read one topic with topic=<name>'), which clarifies the action/topic relationship the schema only hints at.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific role — the first-call onboarding/guidance tool for agents entering Maket — and explicitly disambiguates from the user-facing Help document. The verb+resource is clear ('learn how to operate Maket'), though it never names or contrasts with sibling tools like maket_doc, which could plausibly be confused with a documentation tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a direct usage instruction ('first call for any agent entering Maket') and lays out the three actions with what each returns, so an agent knows which action to pick. It lacks an explicit 'when not to use this' statement, which is minor given how unambiguous the first-call framing is.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
When to use: add a diagram to a page. Works for flowcharts, sequence, class, ER, state, and XY chart diagrams. Pick this over manual SVG or nested divs when the thing you want is conceptually a graph.
Renders Mermaid syntax to durable inline SVG and injects it into the page HTML. The answer gives the document's reading path in Maket and the rendered diagram as an inline image (at most 1600 px and 1 MB of base64; beyond a 2:1 ratio, its top or left part). The source and semantic rendering choices stay on the wrapper so charte changes can rerender the diagram. The diagram scales with its wrapper (width/height drive the frame, not the SVG itself). If dataId already exists, the diagram is replaced in place — idempotent edits. A document charte is applied automatically through canonical diagram tokens and documented color/font fallbacks. tokenRefs selects any existing charte token explicitly; direct safe values take final precedence. Density controls are supported for flowchart and state diagrams by the current renderer. Source-level Mermaid styling directives are rejected; use charte tokens or safe diagram options. Header on its own line: graph TD\n A-->B (NOT graph TD; A-->B)
| Name | Required | Description | Default |
|---|---|---|---|
| bg | No | Safe background colour. Overrides charte, profile, or tokenRefs. | |
| fg | No | Safe foreground colour. Overrides charte, profile, or tokenRefs. | |
| doc | Yes | Document name | |
| code | Yes | Mermaid diagram syntax. Header on its own line, then statements. E.g. "graph TD\n A-->B\n B-->C". | |
| font | No | Safe primary font family. A fallback stack is normalized to its first family. Overrides charte, profile, or tokenRefs. | |
| line | No | Safe connector colour. Overrides charte, profile, or tokenRefs. | |
| page | Yes | Page number (1-based) | |
| muted | No | Secondary text colour. Overrides charte, profile, or tokenRefs. | |
| theme | No | Optional built-in diagram profile. Overrides automatic charte defaults; tokenRefs and direct values override it. | |
| width | No | CSS width for the wrapper (e.g. "180mm", "100%"). Default: auto. | |
| accent | No | Safe arrow/accent colour. Overrides charte, profile, or tokenRefs. | |
| border | No | Node and group border colour. Overrides charte, profile, or tokenRefs. | |
| dataId | No | data-id for the wrapper element. Default: auto-generated (mermaid-1, mermaid-2...) | |
| height | No | CSS height for the wrapper (e.g. "120mm"). Default: auto. | |
| padding | No | Flowchart/state canvas padding in px. | |
| surface | No | Node surface colour. Overrides charte, profile, or tokenRefs. | |
| position | No | Where to insert relative to target. Default: beforeend. | |
| targetId | No | data-id of parent element to insert into. Default: page root. | |
| tokenRefs | No | Explicit references to tokens on the document charte, keyed by diagram role. Example: {"bg":"color.paper","accent":"color.primary","font":"font.body"}. | |
| nodeSpacing | No | Flowchart/state horizontal spacing between sibling nodes in px. | |
| transparent | No | Render without an SVG background. Default: false. | |
| layerSpacing | No | Flowchart/state vertical spacing between diagram layers in px. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so: it discloses the return payload (reading path plus inline image, capped at 1600 px / 1 MB base64, cropped beyond a 2:1 ratio), idempotent in-place replacement when dataId already exists, automatic charte application with an explicit precedence order, and renderer support limits for density controls. This is exactly the operational context annotations would otherwise supply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the usage trigger and dense with non-redundant rules; nearly every sentence adds a constraint. The header-format reminder ("header on its own line... NOT graph TD; A-->B") repeats what the code parameter schema already documents, a minor redundancy in an otherwise tight block.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 22-parameter mutation tool with no annotations and no output schema, the description covers the return value, idempotency, styling limitations, scaling behavior, and theming precedence — the gaps an agent would otherwise have to discover by trial. Nothing essential to correct invocation appears missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond it: precedence across charte vs tokenRefs vs direct safe values, the fact that source/semantic choices are persisted on the wrapper so charte changes can rerender, and that padding/nodeSpacing/layerSpacing only apply to flowchart and state diagrams. The precedence rule partially duplicates schema wording, which keeps this from a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Renders Mermaid syntax to durable inline SVG and injects it into the page HTML") and enumerates supported diagram types (flowchart, sequence, class, ER, state, XY). It also distinguishes itself from competing approaches ("Pick this over manual SVG or nested divs when the thing you want is conceptually a graph"), so an agent can route correctly without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Opens with an explicit "When to use: add a diagram to a page" trigger and names alternatives plus the condition that selects this tool over them. It also states a constraint that functions as a when-not ("Source-level Mermaid styling directives are rejected; use charte tokens or safe diagram options"), leaving little to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
When to use: manage page structure within a document — add, remove, rename, reorder, list. For page content, use maket_html instead.
Manage pages within a document. HTML can embed the current JSON Forms template at . add — append a page with html, json_forms, or both with one form slot; sets it active. remove — delete a page by 1-based index or name; refused if it's the last page. rename — rename a page by index or current name. reorder — move a page from one 1-based position to another; activePage adjusts. list — list pages with their template format; the active page is marked ●. set_form — replace the current form, preserving HTML with a form slot; without a slot, switch to a full-page form. get_form — read one page's JSON Forms template.
Note: charte compliance (token-literal colours, font-family, box-shadow) is enforced by maket_html set/patch, not by maket_page add. If the new page must match a charte, follow maket_page add with maket_html set to validate.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | For reorder: target 1-based position. | |
| doc | Yes | Document name (always required). | |
| from | No | For reorder: source 1-based position. | |
| html | No | For add: HTML body for the new page. Relative image src values are normalized to /assets/... | |
| name | No | For add/rename: page name (new page name, or rename target). | |
| page | No | For remove/rename: target page — either 1-based index or page name. | |
| action | Yes | Operation to run. See the tool description for the action table. | |
| json_forms | No | For add/set_form: JSON Forms template. Omit uischema to generate the form from the document-state JSON Schema. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does well: remove is 'refused if it's the last page', add 'sets it active', reorder makes 'activePage adjust', list marks the active page with ●, and set_form preserves HTML when a slot exists. It omits error shapes, permission/auth requirements, and whether rename/reorder are atomic, which keeps it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the when-to-use decision, then a scannable one-line-per-action table, then a caveat note. Every sentence maps to a decision the agent must make; nothing is padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter, 7-action tool with no annotations and no output schema, the description is substantially complete: it covers each action, side effects, the last-page guard, and the charte-validation follow-up. It stops short of describing return payloads beyond the list marker and any failure modes other than the last-page refusal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already documents from/to/page/name/html per action, so the description's action table largely restates structured data. It adds a little beyond the schema (one form slot per page, activePage side effects, uischema omission generating a form), but the baseline of 3 for high-coverage schemas is the right level.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Manage pages within a document') and enumerates the exact operations (add, remove, rename, reorder, list, set_form, get_form). It explicitly distinguishes itself from the sibling maket_html by scope: structure here, content there.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Opens with an explicit 'When to use' clause and names the alternative for the excluded case ('For page content, use maket_html instead'). The trailing note further routes the agent: charte compliance must be validated via maket_html set, not via this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
When to use: export a document to PDF for sharing or print. One call renders every page in order. For a single-page raster (PNG), use maket_preview snapshot instead.
Renders every page via headless Chromium at the canvas's true mm size, then writes to EXPORTS_DIR/.pdf. Charte CSS is inlined so fonts and tokens render identically to the live preview. The result lists, by number and name, every page whose PDF rendering differs from its preview (element boxes, fonts, colours). quality — screen (96 DPI, smallest), print (150 DPI, default), hd (300 DPI). rows — collection-bound pages: preview (default, follows the page cursor), current (cursor row only), all (one page per row), template (raw placeholders). Check the cursor first with maket_collection action=cursor.
| Name | Required | Description | Default |
|---|---|---|---|
| doc | Yes | Document name. | |
| rows | No | For pages bound to a collection: preview (default) follows each page's cursor — what the live canvas shows; current = the cursor's row only; all = one page per row (mail merge); template = raw placeholders. | |
| quality | No | DPI preset: screen=96, print=150 (default), hd=300. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so: it discloses the rendering engine (headless Chromium), the true mm rendering size, the exact write destination (EXPORTS_DIR/<doc>.pdf), the CSS inlining behavior that guarantees fidelity, and what the result reports (pages whose rendering differs from preview). That is unusually complete for a mutation/export tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the usage decision, then behaviors, then parameter notes — a sensible hierarchy with no wasted preamble. It is somewhat long, and the quality/rows lines duplicate what the schema already says, so it falls short of a crisp 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three straightforward parameters, no output schema, and no annotations, the description covers everything an agent needs: purpose, alternative, side effects, output location, and even a summary of the return content. Nothing material is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters and both enums. The description largely restates the enum semantics (quality DPI presets, rows preview/current/all/template) rather than adding new meaning, though the cursor cross-reference is a small value-add. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ("export a document to PDF for sharing or print") and immediately distinguishes itself from the sibling maket_preview by naming the alternative for raster output. An agent can route between maket_pdf and maket_preview without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit "When to use" framing plus an explicit when-not: "For a single-page raster (PNG), use maket_preview snapshot instead." It also supplies a prerequisite workflow hint for collection-bound pages ("Check the cursor first with maket_collection action=cursor").
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
When to use: view documents outside the agent. open flips the live preview URL into the user's browser; snapshot rasterises a single page to PNG at its true mm size; show puts pages in front of the user inside the conversation.
open — launch the live preview URL (localhost) in the default browser. No params. snapshot — render a page via headless Chromium. Returns the full-size PNG as a file path on disk, the page's reading path in Maket, and the image inline (at most 1600 px on its longest side and 1 MB of base64, downscaled when larger; beyond a 2:1 ratio, the top or left part of the page). On hosts that render MCP Apps, the Maket reader also opens on that page. show — on hosts that render MCP Apps, open the Maket reader in the conversation: doc, pages ("all", 3, "3-5" or [1,4]), layout (scroll | page), start (page to open at), zoom (fit-width | actual). The user can then switch layout, jump through the page list, zoom and open the document in Maket. Other hosts get the reading path. Returns no image: use snapshot to inspect a page yourself.
| Name | Required | Description | Default |
|---|---|---|---|
| doc | No | Document name. Required for snapshot and show. | |
| page | No | 1-based page number. Required for snapshot. | |
| path | No | For snapshot: output PNG path. Defaults to EXPORTS_DIR/<doc>.png. | |
| zoom | No | For show: fit-width (default) or actual size. | |
| pages | No | For show: "all" (default), a page number, a range such as "3-5", or a list of page numbers. | |
| start | No | For show: the page number to open at, one of the shown pages (default: the first). | |
| action | Yes | Operation to run. See the tool description for the action table. | |
| layout | No | For show: scroll (default) shows the pages one after another; page shows one at a time with previous and next. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries the full behavioral burden and does so well: headless Chromium rendering, a PNG written to a file path on disk, inline image caps (1600 px longest side, 1 MB base64, downscaling, 2:1 ratio cropping to the top/left), and host-dependent side effects (reader opening, browser launch). This is far more than the schema or annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The block is dense but well structured: a when-to-use header followed by an aligned action table, with no filler sentences. It loses a point because the `show` line re-enumerates doc/pages/layout/start/zoom values that the 100%-covered schema already lists, which is mild duplication.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter, three-mode tool with no output schema and no annotations, the description covers what each action returns (file path, reading path, inline image, or nothing), which parameters each action needs, and host-dependent variations. An agent has everything required to pick an action and call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is already 100%, so the baseline is 3. The description goes beyond it by giving concrete syntax for `pages` ('all', 3, "3-5", [1,4]) and a semantic constraint for `start` ('one of the shown pages, default: the first'), which the schema's generic integer description does not state.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening line states a specific purpose ('view documents outside the agent') and the action table gives a precise verb+resource for each of the three modes (open = launch live preview URL, snapshot = rasterise a page to PNG, show = display pages in the conversation). It does not, however, differentiate itself from any of the 15 sibling tools (e.g. maket_reader, maket_pdf, maket_canvas), so an agent cannot rule those out from this text alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is front-loaded ('When to use: view documents outside the agent') and each action carries its own selection condition. It even routes away from itself explicitly: 'Returns no image: use snapshot to inspect a page yourself', and notes host-conditional behavior ('on hosts that render MCP Apps... Other hosts get the reading path').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calls of the Maket reader view (ui://maket/page): page returns one rendered page without image data, image returns one of its images downscaled to the displayed width, write sets one value of a state document as the Maket form does. Not for agents.
| Name | Required | Description | Default |
|---|---|---|---|
| op | No | For write: patch op. | |
| doc | Yes | Document name. | |
| file | No | For image: the asset file, one of the page's images. | |
| page | No | For page and image: 1-based page number. | |
| path | No | For write: JSON Pointer of the value. | |
| value | No | For write: the new value. | |
| width | No | For image: displayed width in device pixels. | |
| action | Yes | page, image or write. | |
| expectedRevision | No | For write: the state revision the value was edited from. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose per-action return behavior (page returns one rendered page without image data; image returns a downscaled image; write mutates a state document). However it omits mutation risks such as revision conflicts or permission needs, and the 'Not for agents' caveat adds behavioral ambiguity rather than clarity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that maps each action to its effect with no filler. It is dense but every clause describes a distinct operation, though the trailing 'Not for agents' clause is questionable rather than load-bearing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter, three-action tool with no annotations and no output schema, the description covers the actions and their return shapes adequately. It nonetheless leaves concurrency/permission behavior for the write action unaddressed and includes the confusing 'Not for agents' caveat, so it is only marginally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents each parameter including the action enum and the write-only fields (op, path, value, expectedRevision). The description adds only high-level context ('write sets one value of a state document') and no syntax or format detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (the Maket reader view) and enumerates its three operations (page, image, write) with what each does. An agent can grasp the scope, though 'Calls of the Maket reader view' is slightly awkward and the tool is not clearly distinguished from siblings like maket_page or maket_image.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use guidance and no alternatives are named, despite closely related siblings (maket_page, maket_image, maket_state). The only routing cue is the puzzling 'Not for agents', which gives no positive condition for selection and is likely to mislead rather than guide an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
When to use: attach durable data and immutable snapshot history to one living document.
Document state is separate from collections and mail merge. A state-backed document renders Mustache variables, sections, inverted sections, and loops from its latest revision. Every mutation stores a complete validated schema + data snapshot. History is unbounded unless the document has a revision retention.
The page interface is HTML/CSS, a JSON Forms template, or HTML embedding the current form at . Configure the form with maket_page set_form. HTML uses display-only Mustache plus explicit data-maket-bind controls. JSON Forms uses the document-state JSON Schema and data, with an optional UI schema. Both formats resolve to the same JSON Pointer patches and revisioned store.
init — attach a schema and initial data to a static document (revision 1; no expected_revision).
get — read the schema, the revision retention (retention, null when unbounded), and the current revision.
update — append a complete state snapshot; expected_revision is required.
patch — apply RFC 6902 JSON Patch operations; expected_revision is required.
validate_schema — validate a proposed schema against current or supplied data without saving.
change_schema — atomically replace the schema and append compatible data; expected_revision is required.
history — list immutable revisions newest first.
revision — read one revision.
restore — append a new revision containing an older schema + data snapshot; expected_revision is required.
set_retention — keep retention previous revisions besides the current one and delete older ones now and after every later write; 0 keeps only the current state, null restores unbounded history. Applies to Workspace items and collection projections too.
| Name | Required | Description | Default |
|---|---|---|---|
| doc | Yes | Target document name. | |
| data | No | Complete state object required by init/update; optional compatible data for schema validation/change. | |
| patch | No | RFC 6902 operations required by action=patch. | |
| action | Yes | Document-state operation to perform. | |
| schema | No | JSON Schema required by init, validate_schema, and change_schema. | |
| revision | No | Historical revision required by revision and restore. | |
| retention | No | For set_retention: number of previous revisions kept besides the current one (0 keeps only the current state); null keeps the full history again. | |
| expected_revision | No | Current revision required by update, patch, change_schema, and restore; not used by init. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and does well: it discloses that every mutation stores a complete validated snapshot, that history is unbounded unless retention is set, that set_retention deletes older revisions immediately and after every later write, and that it also affects Workspace items and collection projections. It does not describe optimistic-concurrency failure behavior when expected_revision is stale, nor permissions/auth, which keeps it short of 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the use case and alternative tools, then a compact action reference table where each line earns its place. The HTML/JSON Forms page-interface paragraph is longer and more tangential than the rest, and is the one section that could be trimmed, otherwise dense and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter action-dispatch tool with no output schema and no annotations, the description is thorough: it defines all actions, mutation preconditions, and retention side effects. It leaves return shapes partially implicit (e.g., what history/revision return) and omits failure modes, but is otherwise complete enough to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 8 parameters (baseline 3). The description adds real meaning on top: which actions require expected_revision, which require a complete data object vs optional data, and the exact semantics of retention (0 vs null). It stops short of explaining JSON Pointer/patch path conventions, so 4 rather than 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource: 'attach durable data and immutable snapshot history to one living document.' It explicitly distinguishes itself from collections and mail merge, and enumerates all ten actions with a one-line meaning each, so an agent can identify the tool and the operation without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Leads with 'When to use:' and names the alternatives it is not (collections, mail merge). Per-action notes state preconditions (expected_revision required by update/patch/change_schema/restore; init uses revision 1 with no expected_revision), which is exactly the when-to-use detail an agent needs to pick correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
When to use: create and operate a Structured Workspace — a schema-driven collection of items, listed in an index and opened as Maket documents built from templates.
Method (full recipe: maket_learn action=topic topic=structured-workspaces): 1) create with a data_schema alone that has a required "id" property (string), one value per item: Maket identifies the items by "/id" — or declare another identity per collection, e.g. representation_schema={"collections":{"items":{"name":"Items","identity":"/code"}}} — and Maket writes the index, detail, card templates and the detail form itself, in the Workspace category; 2) add_item; 3) check, which must answer verdict ready. Inline template HTML (detailTemplateHtml, compactTemplateHtml, indexTemplateHtml, detailForm) or names of existing template documents are the optional second and third paths.
Identity: every collection has an identity, a JSON Pointer to a required string or number property of its items (e.g. "/code"); without one, "/id" when the schema requires an id property. Its value, as a string, is the item id used everywhere (item=, documents, cursors) and is unique across the whole Workspace, all collections included; Maket never generates one. add_item refuses data without it, or a value another item of the Workspace already bears (invalid_record, naming that item); update_item refuses a change of it: delete and add the item again instead. The identity of a collection holding items cannot be changed.
create and update_definition refuse a definition with errors (isError, one line per error with collection, path and fix) and keep the previous definition; allow_incomplete=true persists it anyway. add_item and update_item refuse data that breaks the schema with its path, rule and fix.
The data schema validates every item. The representation schema declares one or more collections; each collection owns its global template and binds concrete schema paths to compact and detail templates. The item source holds the item data; an item's document is created from its detail template when the item is opened or exported. Template-controlled pages are synchronized from the template; instance-owned pages remain in the same document.
Reading items is a cursor query: view answers one batch of item summaries for one collection (collection, default the first) with next (an opaque cursor, absent once the listing is exhausted), total and the group counts. Pass text (searches searchFields, by default every text property, ignoring case and accents), filters ([{"field":"/status","op":"eq","value":"todo"}], op in for a list), sort ({"field":"/title","direction":"descending"}) and batch (default indexPageSize, 50; at most 500) to start a new query, which also becomes the window every client sees in the index. To read the next batch, pass cursor= with the same query arguments (the answer gives the call in more): it reads the source directly and never depends on the shared window: no item that existed before and kept its sort value is skipped or read twice, while an item whose sort value changes during paging may move across the cursor. There is no page number and no previous: a new query restarts from the first item. view with neither query nor cursor answers the first batch of the collection's own order.
Optional collection grouping: groupBy is a JSON Pointer into item data (e.g. "/status"), groupOrder lists group values to place first, and pageSize (default 24) caps the compact cards per collection page. With groupBy, each item slot receives a group header followed by its cards and the collection document flows onto as many pages as needed; without it, the collection stays one page.
Optional collection sort: sortBy is a JSON Pointer into item data (e.g. "/place") and sortDirection is "ascending" (default) or "descending"; cards are ordered by that value inside each group, or across the slot without groupBy, items without a value last and ties in item id order; without sortBy, insertion order stays.
list — list Structured Workspaces, each prefixed with ready or incomplete.
view — verdict and finding count first, then the definition, item counts, pinned items, owned documents, one batch of the collection window (see the cursor query above), and reading: the reading path of that collection's index in Maket.
check — the doctor: verdict ready or not ready and every finding with severity, object, sentence, fix and next call. Never writes.
create — create a workspace from a data schema, with an optional representation schema; refuses errors unless allow_incomplete=true.
update_definition — validate and replace the data and/or representation contract, then update the item and index documents that exist; an erroneous definition is refused and the previous one kept unless allow_incomplete=true.
add_item — validate data and write the item to its source under the id its identity property holds; its document is created when the item is opened.
update_item — replace item data with optimistic revision control.
delete_item — delete the item from its source, with its document when it was opened.
sync_template — propagate current detail-template pages while preserving instance-owned pages.
rename — rename the Workspace without regenerating owned documents.
delete — atomically delete the Workspace and every document, state revision, and annotation it owns.
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | ||
| item | No | ||
| sort | No | ||
| text | No | ||
| batch | No | ||
| action | Yes | ||
| cursor | No | ||
| binding | No | ||
| filters | No | ||
| new_name | No | ||
| workspace | No | ||
| collection | No | ||
| data_schema | No | ||
| description | No | ||
| document_name | No | ||
| allow_incomplete | No | ||
| expected_revision | No | ||
| representation_schema | No | ||
| expected_workspace_revision | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden and does so thoroughly: it discloses refusal behavior (invalid_record naming the offending item), error formats (one line per error with collection, path and fix), optimistic revision control on update_item, atomic delete semantics, and sync_template's page-preservation behavior. This is unusually rich behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with 'When to use' and method, which is good, but the middle is an extremely dense wall of run-on prose about identity, cursors and grouping that is hard to parse. Given the 11-action/19-param complexity some length is earned, but substantial trimming is possible.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by describing return values in detail (view's verdict, finding count, batch of summaries, next/total/group counts, reading path). For a tool this complex, the coverage of actions, errors and reading semantics is essentially complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% across 19 params, so the description must compensate and largely does: it explains data_schema, representation_schema, collection, cursor, text, filters, sort, batch, allow_incomplete, identity, groupBy/groupOrder/pageSize and sortBy/sortDirection with concrete examples. A few params (description, document_name, binding, expected_workspace_revision) are never addressed, leaving gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with an explicit 'When to use' clause stating the specific verb and resource: 'create and operate a Structured Workspace — a schema-driven collection of items...'. It distinguishes the tool from siblings like maket_workspace and maket_collection by scoping it to schema-driven structured workspaces with templates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit when-to-use, a numbered method (create → add_item → check with verdict ready), and points to an alternative resource for the full recipe ('maket_learn action=topic topic=structured-workspaces'). Each of the 11 actions carries its own usage note, and preconditions (must answer verdict ready) are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
When to use: every session-level interaction with the live workspace — open a doc/page in the preview, inspect a doc's current state, toggle its lock, and process the user-message queue. For persistent CRUD on documents (create, rename, delete, duplicate, meta, import/export) use maket_doc.
focus — open doc at page page in the live preview (sets active doc + active page).
state — summarise doc's current state: canvas, pages with element counts and data-source cursors (collection · mode · row), charte, pending messages.
lock — lock or unlock doc. When locked, every doc-scoped mutation refuses until it's unlocked. Pass locked=true/false, or omit to toggle.
fit_view — zoom out the client to fit the whole workspace (same as the Maximize button).
list_messages — return pending annotations as JSON. With doc, return only that document's messages; without it, return all document and workspace messages. Each message carries docName (or none for workspace scope), pageIndex and elementId for its anchor, text, ts; a note the person changed after sending also carries edited: true and editedAt (epoch ms) — act on the current text.
ack_messages — drop the given ids from whichever bucket they live in.
| Name | Required | Description | Default |
|---|---|---|---|
| doc | No | The document in scope. Required for focus/state/lock. For list_messages, pass an exact document name to read only its annotations; omit to read all document and workspace messages. | |
| ids | No | For ack_messages: message ids to mark processed. | |
| page | No | For focus: 1-based page number to make active. | |
| action | Yes | Operation to run. See the tool description for the action table. | |
| locked | No | For lock: true to lock the document, false to unlock. Omit to toggle. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and largely meets it: it discloses that locking makes every doc-scoped mutation refuse until unlocked, that focus mutates active doc/page, and that ack_messages drops ids from 'whichever bucket they live in'. It also surfaces the `edited`/`editedAt` semantics and the instruction to act on current text. It does not mention auth/permission requirements or failure modes, which keeps it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the when-to-use clause, then a scannable per-action breakdown where each line earns its place. Dense but not padded; slightly long, though the length is justified by six distinct actions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a multi-action tool with no output schema, the description is thorough: it explains the message payload shape (docName, pageIndex, elementId, text, ts, edited flags) that an agent would otherwise have to guess. Safety/error behavior and lock interaction detail beyond mutations refusing are the only modest gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: per-action parameter usage for `doc`, `page`, `locked`, and `ids`, plus the non-obvious rule that omitting `doc` in list_messages widens to all messages. It goes beyond restating the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific scope statement ('every session-level interaction with the live workspace') and enumerates the six concrete actions (focus, state, lock, fit_view, list_messages, ack_messages). It explicitly names the sibling it is not — persistent CRUD belongs to maket_doc — so an agent can route between the two without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' clause tells the agent exactly when this tool applies, and the follow-up sentence draws the boundary against maket_doc for persistent document CRUD. Each action is annotated with its own condition (e.g. list_messages with/without `doc`, lock omit-to-toggle), leaving little to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.2.0maket_canvas2 fields changedInput schema / properties / format / enumPrevious value: -[
- "A2",
- "A3",
- "A4",
- "A5",
- "A6",
- "A7",
- "A8",
- "DESKTOP",
- "TABLET",
- "MOBILE"
-]New value: +[
+ "A2",
+ "A3",
+ "A4",
+ "A5",
+ "A6",
+ "A7",
+ "A8",
+ "DESKTOP",
+ "TABLET",
+ "MOBILE",
+ "AUTO"
+]Input schema / properties / widthAdded value: +{
+ "description": "Width in millimetres for AUTO format; required on creation. Height follows each page content.",
+ "exclusiveMinimum": 0,
+ "type": "number"
+}maket_doc6 fields changedInput schema / properties / action / enumPrevious value: -[
- "new",
- "list",
- "delete",
- "duplicate",
- "rename",
- "meta",
- "export",
- "import"
-]New value: +[
+ "new",
+ "list",
+ "lookup",
+ "link",
+ "delete",
+ "duplicate",
+ "rename",
+ "meta",
+ "pin",
+ "unpin",
+ "export",
+ "import"
+]Input schema / properties / doc / descriptionPrevious value: -"The doc in scope. Required for every action except list. For new: the new doc's name (must be unique). For delete/meta: the doc to act on. For duplicate/rename: the source doc."New value: +"The doc in scope. Required for every action except list. For lookup: the exact name to read. For new: the new doc's name (must be unique). For delete/meta/pin/unpin: the doc to act on. For duplicate/rename: the source doc."Input schema / properties / format / descriptionPrevious value: -"For new: paper/screen format. Default A3. Paper sizes are mm; DESKTOP/TABLET/MOBILE are screen aspect ratios scaled to mm."New value: +"For new: paper/screen format, or AUTO with width in mm and automatic page height. Default A3. Paper sizes are mm; DESKTOP/TABLET/MOBILE are screen aspect ratios scaled to mm."Input schema / properties / format / enumPrevious value: -[
- "A2",
- "A3",
- "A4",
- "A5",
- "A6",
- "A7",
- "A8",
- "DESKTOP",
- "TABLET",
- "MOBILE"
-]New value: +[
+ "A2",
+ "A3",
+ "A4",
+ "A5",
+ "A6",
+ "A7",
+ "A8",
+ "DESKTOP",
+ "TABLET",
+ "MOBILE",
+ "AUTO"
+]Input schema / properties / responsiveAdded value: +{
+ "description": "For new/meta: opt this entire document into fluid browser reading at its available pane width. Default false; canvas authoring and PDF keep their physical dimensions. On a Workspace template only this field may be changed through meta; then sync_template propagates it to projections.",
+ "type": "boolean"
+}Input schema / properties / widthAdded value: +{
+ "description": "Width in millimetres for AUTO format; required on creation. Height follows each page content.",
+ "exclusiveMinimum": 0,
+ "type": "number"
+}maket_learn1 field changedInput schema / properties / topic / enumPrevious value: -[
- "overview",
- "workflow",
- "tools",
- "html",
- "chartes",
- "diagrams",
- "collections",
- "state",
- "review",
- "install",
- "gemini"
-]New value: +[
+ "overview",
+ "workflow",
+ "tools",
+ "html",
+ "chartes",
+ "diagrams",
+ "collections",
+ "state",
+ "structured-workspaces",
+ "review",
+ "install",
+ "gemini"
+]maket_page2 fields changedInput schema / properties / action / enumPrevious value: -[
- "add",
- "remove",
- "rename",
- "reorder",
- "list"
-]New value: +[
+ "add",
+ "remove",
+ "rename",
+ "reorder",
+ "list",
+ "set_form",
+ "get_form"
+]Input schema / properties / json_formsAdded value: +{
+ "description": "For add/set_form: JSON Forms template. Omit uischema to generate the form from the document-state JSON Schema.",
+ "properties": {
+ "uischema": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ }
+ },
+ "type": "object"
+}maket_preview6 fields changedInput schema / properties / action / enumPrevious value: -[
- "open",
- "snapshot"
-]New value: +[
+ "open",
+ "snapshot",
+ "show"
+]Input schema / properties / doc / descriptionPrevious value: -"Document name. Required for snapshot."New value: +"Document name. Required for snapshot and show."Input schema / properties / layoutAdded value: +{
+ "description": "For show: scroll (default) shows the pages one after another; page shows one at a time with previous and next.",
+ "enum": [
+ "scroll",
+ "page"
+ ],
+ "type": "string"
+}Input schema / properties / pagesAdded value: +{
+ "anyOf": [
+ {
+ "const": "all",
+ "type": "string"
+ },
+ {
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ {
+ "pattern": "^\\d+\\s*-\\s*\\d+$",
+ "type": "string"
+ },
+ {
+ "items": {
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "minItems": 1,
+ "type": "array"
+ }
+ ],
+ "description": "For show: \"all\" (default), a page number, a range such as \"3-5\", or a list of page numbers."
+}Input schema / properties / startAdded value: +{
+ "description": "For show: the page number to open at, one of the shown pages (default: the first).",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+}Input schema / properties / zoomAdded value: +{
+ "description": "For show: fit-width (default) or actual size.",
+ "enum": [
+ "fit-width",
+ "actual"
+ ],
+ "type": "string"
+}maket_readermaket_state2 fields changedInput schema / properties / action / enumPrevious value: -[
- "init",
- "get",
- "update",
- "patch",
- "validate_schema",
- "change_schema",
- "history",
- "revision",
- "restore"
-]New value: +[
+ "init",
+ "get",
+ "update",
+ "patch",
+ "validate_schema",
+ "change_schema",
+ "history",
+ "revision",
+ "restore",
+ "set_retention"
+]Input schema / properties / retentionAdded value: +{
+ "anyOf": [
+ {
+ "maximum": 9007199254740991,
+ "minimum": 0,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "For set_retention: number of previous revisions kept besides the current one (0 keeps only the current state); null keeps the full history again."
+}maket_structured_workspacemaket_workspace1 field changedInput schema / properties / doc / descriptionPrevious value: -"The document in scope. Required for focus/state/lock. Do not pass it for list_messages; that action returns every queued user message across all documents and the workspace."New value: +"The document in scope. Required for focus/state/lock. For list_messages, pass an exact document name to read only its annotations; omit to read all document and workspace messages."v2.1.0maket_charte1 field changedInput schema / properties / tokens / descriptionPrevious value: -"For set: design tokens grouped by category. Become CSS variables --charte-<group>-<key>. Example: {\"color\": {\"primary\": \"#2563EB\"}, \"font\": {\"heading\": \"Montserrat\"}, \"spacing\": {\"page\": \"20mm\"}}."New value: +"For set: design tokens grouped by category. Become CSS variables --charte-<group>-<key>. Diagram roles can use a canonical \"diagram\" group (bg, fg, line, accent, muted, surface, border, font, padding, nodeSpacing, layerSpacing, transparent). Example: {\"color\":{\"primary\":\"#2563EB\"},\"font\":{\"body\":\"Montserrat\"},\"diagram\":{\"surface\":\"#EFF6FF\",\"nodeSpacing\":\"32px\"}}."maket_learn1 field changedInput schema / properties / topic / enumPrevious value: -[
- "overview",
- "workflow",
- "html",
- "chartes",
- "collections",
- "state",
- "review",
- "install",
- "gemini"
-]New value: +[
+ "overview",
+ "workflow",
+ "tools",
+ "html",
+ "chartes",
+ "diagrams",
+ "collections",
+ "state",
+ "review",
+ "install",
+ "gemini"
+]maket_mermaid14 fields changedInput schema / properties / accent / descriptionPrevious value: -"Arrow/accent color (hex). Overrides theme accent."New value: +"Safe arrow/accent colour. Overrides charte, profile, or tokenRefs."Input schema / properties / bg / descriptionPrevious value: -"Background color (hex). Overrides theme bg."New value: +"Safe background colour. Overrides charte, profile, or tokenRefs."Input schema / properties / borderAdded value: +{
+ "description": "Node and group border colour. Overrides charte, profile, or tokenRefs.",
+ "type": "string"
+}Input schema / properties / fg / descriptionPrevious value: -"Text/foreground color (hex). Overrides theme fg."New value: +"Safe foreground colour. Overrides charte, profile, or tokenRefs."Input schema / properties / fontAdded value: +{
+ "description": "Safe primary font family. A fallback stack is normalized to its first family. Overrides charte, profile, or tokenRefs.",
+ "type": "string"
+}Input schema / properties / layerSpacingAdded value: +{
+ "description": "Flowchart/state vertical spacing between diagram layers in px.",
+ "maximum": 1000,
+ "minimum": 0,
+ "type": "number"
+}Input schema / properties / line / descriptionPrevious value: -"Line/connection color (hex). Overrides theme line."New value: +"Safe connector colour. Overrides charte, profile, or tokenRefs."Input schema / properties / mutedAdded value: +{
+ "description": "Secondary text colour. Overrides charte, profile, or tokenRefs.",
+ "type": "string"
+}Input schema / properties / nodeSpacingAdded value: +{
+ "description": "Flowchart/state horizontal spacing between sibling nodes in px.",
+ "maximum": 1000,
+ "minimum": 0,
+ "type": "number"
+}Input schema / properties / paddingAdded value: +{
+ "description": "Flowchart/state canvas padding in px.",
+ "maximum": 1000,
+ "minimum": 0,
+ "type": "number"
+}Input schema / properties / surfaceAdded value: +{
+ "description": "Node surface colour. Overrides charte, profile, or tokenRefs.",
+ "type": "string"
+}Input schema / properties / theme / descriptionPrevious value: -"Built-in theme name. Can be combined with custom color overrides."New value: +"Optional built-in diagram profile. Overrides automatic charte defaults; tokenRefs and direct values override it."Input schema / properties / tokenRefsAdded value: +{
+ "additionalProperties": false,
+ "description": "Explicit references to tokens on the document charte, keyed by diagram role. Example: {\"bg\":\"color.paper\",\"accent\":\"color.primary\",\"font\":\"font.body\"}.",
+ "properties": {
+ "accent": {
+ "description": "Charte token reference for accent, as \"group.key\".",
+ "type": "string"
+ },
+ "bg": {
+ "description": "Charte token reference for bg, as \"group.key\".",
+ "type": "string"
+ },
+ "border": {
+ "description": "Charte token reference for border, as \"group.key\".",
+ "type": "string"
+ },
+ "fg": {
+ "description": "Charte token reference for fg, as \"group.key\".",
+ "type": "string"
+ },
+ "font": {
+ "description": "Charte token reference for font, as \"group.key\".",
+ "type": "string"
+ },
+ "layerSpacing": {
+ "description": "Charte token reference for layerSpacing, as \"group.key\".",
+ "type": "string"
+ },
+ "line": {
+ "description": "Charte token reference for line, as \"group.key\".",
+ "type": "string"
+ },
+ "muted": {
+ "description": "Charte token reference for muted, as \"group.key\".",
+ "type": "string"
+ },
+ "nodeSpacing": {
+ "description": "Charte token reference for nodeSpacing, as \"group.key\".",
+ "type": "string"
+ },
+ "padding": {
+ "description": "Charte token reference for padding, as \"group.key\".",
+ "type": "string"
+ },
+ "surface": {
+ "description": "Charte token reference for surface, as \"group.key\".",
+ "type": "string"
+ },
+ "transparent": {
+ "description": "Charte token reference for transparent, as \"group.key\".",
+ "type": "string"
+ }
+ },
+ "type": "object"
+}Input schema / properties / transparentAdded value: +{
+ "description": "Render without an SVG background. Default: false.",
+ "type": "boolean"
+}v1.7.0maket_canvas1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"maket_charte1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"maket_collection1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"maket_doc2 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / properties / category / descriptionPrevious value: -"For new/meta: category tag used for grouping in list (default general)."New value: +"For new/meta: category path separated by / (for example clients/acme). Flat values remain valid roots; default general."maket_gmail1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"maket_html1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"maket_image1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"maket_learn1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"maket_mermaid1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"maket_page1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"maket_pdf1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"maket_preview1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"maket_state1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"maket_workspace1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"v1.5.0maket_html1 field changedInput schema / properties / ops / descriptionPrevious value: -"For patch: list of surgical ops by data-id. Each op has `id` plus one of: style (object), content (string), attr (object), insert (html) + optional position, replace (outerHTML), remove (true), clone (newId), moveTo (targetId) + optional position."New value: +"For patch: list of surgical ops by data-id. Each op has `id` plus one of: style (object), content (string), attr (object), insert (html) + optional position, replace (outerHTML), remove (true), clone (newId), moveTo (targetId) + optional position. To exclude one intentional non-interactive leaf decoration with no child elements or text from layout validation, patch that existing element with attr: {\"data-maket-layout\":\"ignore\"}; controls, links, data-maket-bind and focusable/ARIA elements are ineligible. This override is rejected in set/insert/replace/content HTML, and its enabling op must be the only op in the patch request."maket_learn1 field changedInput schema / properties / topic / enumPrevious value: -[
- "overview",
- "workflow",
- "html",
- "chartes",
- "collections",
- "review",
- "install",
- "gemini"
-]New value: +[
+ "overview",
+ "workflow",
+ "html",
+ "chartes",
+ "collections",
+ "state",
+ "review",
+ "install",
+ "gemini"
+]maket_statev1.4.5maket_collection2 fields changedInput schema / properties / action / enumPrevious value: -[
- "list",
- "view",
- "create",
- "validate_schema",
- "change_schema",
- "add_row",
- "update_row",
- "delete_row",
- "delete",
- "bind",
- "unbind"
-]New value: +[
+ "list",
+ "view",
+ "create",
+ "validate_schema",
+ "change_schema",
+ "add_row",
+ "update_row",
+ "delete_row",
+ "delete",
+ "bind",
+ "unbind",
+ "cursor"
+]Input schema / properties / modeAdded value: +{
+ "enum": [
+ "template",
+ "rendered",
+ "all"
+ ],
+ "type": "string"
+}maket_pdf1 field changedInput schema / properties / rowsAdded value: +{
+ "description": "For pages bound to a collection: preview (default) follows each page's cursor — what the live canvas shows; current = the cursor's row only; all = one page per row (mail merge); template = raw placeholders.",
+ "enum": [
+ "preview",
+ "current",
+ "all",
+ "template"
+ ],
+ "type": "string"
+}v0.1.0maket_canvasmaket_chartemaket_collectionmaket_docmaket_gmailmaket_htmlmaket_imagemaket_learnmaket_mermaidmaket_pagemaket_pdfmaket_previewmaket_workspaceScored across 16 tools
Each tool is scoped to a distinct domain and most descriptions open with explicit 'when to use' plus cross-references (doc vs workspace, page vs html, pdf vs preview snapshot), which sharply limits misselection. Remaining overlap risk is modest: maket_collection and maket_structured_workspace both deal with schema-driven item stores, and maket_preview/maket_pdf/maket_reader form a rendering cluster that requires reading descriptions carefully.
Every tool uses the same maket_ + snake_case noun pattern (maket_doc, maket_page, maket_html, maket_charte, maket_collection), with no camelCase or verb-style deviations. Sub-actions are uniformly lowercase snake_case (add_item, validate_schema, set_retention), so the surface is highly predictable.
16 tools is slightly above the ideal band but justified by a genuinely broad platform spanning documents, pages, HTML, canvas, state, collections, chartes, images, exports, preview and Gmail. Each top-level tool owns a real domain, though a few (maket_reader, maket_learn) are peripheral to agent workflows.
Lifecycle coverage is strong: full CRUD on documents, pages, state revisions, collections, chartes, assets and Structured Workspaces, plus import/export/PDF paths. Minor gaps remain, such as no tool for agents to create user annotations (only list/ack) and no cross-document content search beyond list/lookup.
Visual email & layout builder that turns AI assistants into a Temway authoring studio.
Design on-brand emails with your AI, preview them in chat, and send through server-side guardrails.
Give your AI agents a design superpower. Generate, edit, and publish publication-grade decks, reports, landing pages, resumes, and marketing visuals directly within your agent workflow. Delivering frontier-level design quality at 3× the speed and 53× lower cost -from conversational prompt to live link or vector PDF in minutes.
Agent-Native design tool - create and edit visual designs with agent assistance
