sandbox_architecture

Draws how the parts fit together before you build them: a box per app, service, database, queue or outside API and an arrow for who calls whom, laid out top to bottom automatically as a plain, clean diagram (straight arrows, rounded boxes, what is new in blue), in the result and on the design's page in the person's app. No box is needed.

Its tool title (the MCP title, which some clients show for the tool) is Draw an architecture diagram; it is annotated readOnlyHint: false (each successful call saves a version), destructiveHint: false and openWorldHint: false.

When to use it

The order of work for anything new or changed is: sandbox_draft (screens) → sandbox_architecture (services) → sandbox_schema (stored data) → build in the box → sandbox_review. Skip a step only when the task does not touch it: a change inside one service has no architecture diagram.

Use sandbox_architecture when the work adds or changes services (a new worker, a queue, a call to an outside API, a service that now calls another), or the person asks for an architecture or flow diagram (架構圖, 構成図). Do not make Mermaid, HTML, SVG or image files for this instead: this tool draws it, keeps every version, and gives the person the tools to answer.

It works like sandbox_draft in everything but the drawing: it needs no box, and the design belongs to the account and this conversation, staying when a box stops. id is optional: pass the box of this piece of work to show the design on that box's page too; drawing happens on the server and never wakes a frozen box, and with id naming a box that has not stopped, a successful call counts as use of it and makes your conversation its holder (sandbox_draft).

What to draw

new: true marks the nodes and arrows that are new or different compared with how things are now: they are drawn blue; gray is what stays as it is. The diagram uses no red. It compares with the system as it is now, not with the previous version: what changed since the previous version goes in note, written in blue under the title. The legend at the top right (blue is new or changed, black and gray as it is) and the words before note follow the account's language (Fixed words on the picture). Name the nodes after the box's services, with the service's name in sub (as declared in sandbox_start; before you have declared it, the name you will run it under), so the person can match the diagram to the box. Write labels in the language the person reads.

nodes:

edges:

The diagram is drawn plainly, not hand-drawn: a white background, rounded rectangles with a gray outline and a very light gray fill, straight arrows with solid heads that end at the box's edge, and a regular sans-serif typeface. You give no positions. Nodes are laid out top to bottom in layers: those no arrow points to, and unconnected ones, on top; each other node as many layers down as the longest path to it. Arrows that go around in a loop are drawn as given. Each layer is ordered to cross as few arrows as possible, an arrow that skips layers passes between the boxes, and labels sit beside their lines on a white background. The picture is at least 1200 px wide; past 2400 px it is shrunk to fit, and below 60% warnings suggests splitting it into two diagrams. Characters the typeface lacks, such as emoji, are drawn as boxes and named in warnings: replace them and draw again.

A misspelled or extra field is an error that lists what is allowed; nothing is ignored silently. Everything in the call except id, topic and note is the drawing's spec, at most 64 KB of JSON.

Example

{
  "topic": "Booking and reminders",
  "nodes": [
    { "id": "web", "label": "Mobile web", "sub": "flowday-web" },
    { "id": "api", "label": "API", "sub": "flowday-api" },
    { "id": "db", "label": "Postgres" },
    { "id": "worker", "label": "Reminders", "sub": "flowday-worker", "new": true }
  ],
  "edges": [
    { "from": "web", "to": "api", "label": "HTTPS" },
    { "from": "api", "to": "db", "label": "read and write" },
    { "from": "api", "to": "worker", "label": "schedule", "new": true },
    { "from": "worker", "to": "db", "label": "read the list", "new": true }
  ]
}

The result, their feedback and the next version

• The picture follows the JSON as image content: look at it, then tell the person in one line what to look at. designId (dsg_…) is the design, the same for every version of this topic, reviewId (dsn_…) is this version's id, version counts per account, kind and topic (whichever box you pass or none), appUrl is the design's page in the app, /design/<designId> (anyone with the link can open it; only the account sends feedback), boxId is the box you passed as id (missing without one), imageUrls are download URLs valid one hour, and warnings names a diagram that was shrunk or characters the font lacks.
• The person sees it on the design's page in their app and in the Designs list, and on the box's page under Architecture when you passed a box's id; tapping the picture opens it whole, with pinch zoom, and Report here under it starts a report on it. Their report on a version comes back to the conversation that drew it, like review feedback, with or without a box: it wakes a conversation set up for app feedback, or arrives as fromHuman on this conversation's next call to a design tool or to any tool on a box, or through Copy message for AI; read it with sandbox_report and reportId alone, no id. The message says Feedback on architecture "<topic>" v<n>: …; read the circled pictures, the voice transcript and the text written on the picture (notes[].labels). The message ends with Change it as asked, then call sandbox_architecture again with the same topic for the next version. For it to return to this conversation on its own, the adapter must be 0.6.0 or later (0.5.4 or later when you passed a box's id), and Claude Code's and Gemini CLI's feedback hooks must have been installed with 0.5.4 or later (What automatic return needs). Details: sandbox_draft.
• There is no approval step. Change what they asked, then call sandbox_architecture again with the same topic (and the same id if you passed one), the whole spec again and a one-sentence note on what changed since the previous version: that is the next version (v2, v3…), from any box or none.

Errors

The call fails with a message that names the field; nothing is saved, and it does not count as use of a box: box not found (it must be one of yours; see sandbox_status or GET /v1/boxes) (the id you passed is not a box of this account; leave id out to draw without a box), topic is required: …, topic is at most 80 characters, note is at most 300 characters, spec is at most 64 KB, or what the drawing does not accept, as <path>: <problem>, the path being the arguments of your call:

• edges[0].to: "queue" is not a node id (ids: web, api, db)
• nodes[1].id: duplicate id "api" (also used by spec.nodes[0]): the spec.nodes[0] in parentheses is nodes[0] in your call
• edges[2]: from and to are the same node "api"; self-loops are not supported
• spec: unknown field "edge" (allowed: nodes, edges): a stray or misspelled top-level argument (every argument other than id, topic and note goes to the drawing, which calls them spec together)

Fix that field and call again.

Every tool and topic is listed in the tool reference.