Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@@archsmith/mcp-server Render this architecture IR JSON into an SVG diagram"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ArchSmith turns a validated JSON description of a layered system architecture into a clean, consistent SVG diagram. Feed it a structured document (an IR — intermediate representation), get back a diagram in a fixed, opinionated house style: no per-diagram layout decisions, no hand-drawn boxes, no drift between one architecture doc and the next.
It's built as a library first, a CLI on top of that, and an MCP server on top of that — so it's just as easy for a human to run archsmith render as it is for an AI agent to call it as a tool.
ArchSmith is pre-1.0 — the schema and API may still change (diagram-schema.json itself is marked "first pass, expect revision"). See releases for what's shipped in each version.
Drawing an architecture diagram by hand is slow and doesn't scale: every new diagram means re-deciding box shapes, colors, spacing, and layout from scratch, and keeping a whole set of diagrams visually consistent — a real "house style" — is a losing battle once more than one person is producing them. It's harder still now that agents, not just humans, increasingly need to produce these diagrams: an agent can't open a drawing tool and drag boxes around, but it can absolutely produce structured JSON.
Just asking an LLM to draw an SVG diagram directly doesn't fix this either — it trades manual inconsistency for a different kind, where the same request can come out looking different depending on the day, the model, or the prompt. ArchSmith separates those two concerns instead: an agent (or a human) does the interpretation — turning a sketch or a description into a valid structured document — and hands it to ArchSmith for deterministic rendering. Same input, same output, every time, with the house style (spacing, colors, text wrapping, box shapes) enforced by the renderer rather than re-decided per diagram — down to embedding the exact font text was measured against, so a diagram looks the same on any machine viewing it, not just the one that rendered it.
Related MCP server: Glyphic
ArchSmith currently supports one diagram convention: a layered/swimlane style that lays out a system's architecture as five columns, left to right:
Inbound Actors — who or what calls into the system (end users, other apps, partner integrations).
Ingress — the API gateway/edge layer requests come in through.
Core Platform — the backend itself: API-management/identity concerns, the actual business-logic services, an optional domain-model layer, and the platform's own databases/files ("Systems of Record").
Egress — the gateway layer through which the platform calls out to other systems.
External Systems — downstream dependencies reached via egress, grouped into named clusters.
Every color, box shape, spacing rule, and text-wrapping decision in that layout was pixel-measured against real reference diagrams, not guessed — see packages/schema/README.md for how the sub-layer/color palette is governed as it grows.
Describing an architecture is just picking what goes in each column and writing it down: a title, a short description, and — for items with a role worth flagging, like "the primary database" or "only reached via egress" — a colored dot or a small pill tag. No coordinates, no manual layout, no font-size or spacing decisions to make; the renderer works out box sizes, text wrapping, and alignment from the content alone. See the IR shape below for the actual JSON structure, and Quick start to render one.
Mermaid, PlantUML, and Structurizr (the C4 model's own tool) are the closest comparisons — text/data in, a rendered diagram out, no manual box-dragging. What's different about ArchSmith:
One fixed house style, not a general-purpose diagramming language. Mermaid/PlantUML give you a flexible syntax and largely leave the visual result up to you (or a theme); ArchSmith's IR has no layout or styling knobs at all. The same title/description/color-token input always produces the same box shapes, spacing, and typography, because there's exactly one house style to conform to, not many to choose between.
MCP-first, not just a CLI. The same render/validate capability is a callable MCP tool, with the schema and registries themselves readable as MCP resources — built for an agent to call as part of a larger workflow, not just for a human to paste into a .mmd file.
One diagram convention today. Mermaid/PlantUML/Structurizr all support a broader range of diagram types (sequence diagrams, the full set of C4 levels, state machines) that ArchSmith doesn't attempt yet — see the roadmap-labeled issues for where that could go.
If you want a flexible, general-purpose diagramming syntax, Mermaid or PlantUML are probably the better fit. If you want one specific layered-architecture house style enforced consistently across many diagrams — and want an agent to produce them as easily as a human can — that's what ArchSmith is for.
npm install -g @archsmith/cli
archsmith authorarchsmith author is a guided, no-hand-written-JSON wizard: it walks you through Inbound Actors, Ingress, Core Platform, Systems of Record, Egress, and External Systems one plain-language question at a time, offering only governed colors/sub-layers so whole classes of validation error can't happen — then validates, renders, and saves the .archsmith.json and .svg next to each other. It's aimed at creating a valid initial diagram; editing an existing one isn't supported yet — hand-edit the saved JSON, or start a fresh session, if you spot a mistake afterward.
Name IR documents *.archsmith.json so editors and integrations can identify them without colliding with other JSON-based intermediate representations. The CLI remains filename-agnostic and accepts any JSON file path.
mkdir -p ticket-booking
curl -o ticket-booking/diagram.archsmith.json https://raw.githubusercontent.com/ayeshLK/archsmith/main/examples/ticket-booking/diagram.archsmith.json
archsmith validate ticket-booking/diagram.archsmith.json
archsmith render ticket-booking/diagram.archsmith.json -o ticket-booking/diagram.svgOr without installing anything: npx @archsmith/cli render ticket-booking/diagram.archsmith.json -o ticket-booking/diagram.svg.
Working on ArchSmith itself rather than just using it? See CONTRIBUTING.md for building from a clone.
archsmith author
archsmith validate <input.archsmith.json> [--json]
archsmith render <input.archsmith.json> -o <out.svg> [--no-embed-fonts] [--pretty]
archsmith registries list
archsmith registries show <sub-layers|colors|icons> [--family standard|accessible]
archsmith schema showauthor launches the interactive wizard covered in Quick start above. It needs a real terminal — a piped/non-interactive invocation (e.g. CI) fails with one clear line rather than hanging.
render validates the IR first and fails the same way validate would (exit 1) if it's invalid; a rendering-time error exits 2.
--no-embed-fonts skips embedding the bundled font, producing a smaller file.
--pretty indents the output SVG's element lines for readability (default is one element per line, unindented).
registries show colors --family standard prints just that color family instead of the whole registry. Use --family accessible for the governed color/contrast-safe alternative.
schema show prints the raw diagram-schema.json contents — the structural contract an IR document must satisfy, as distinct from the governed vocabulary registries exposes.
import { render, validate } from "@archsmith/renderer";
const result = validate(ir); // { valid: boolean, errors: string[] }
if (result.valid) {
const svg = render(ir); // complete SVG document, as a string
}@archsmith/mcp-server exposes the same capability as the CLI, over MCP instead of argv — a sibling of the CLI, not a wrapper around it: both call render()/validate() from @archsmith/renderer directly. It communicates over stdio, so an MCP host spawns it as a subprocess and talks JSON-RPC over stdin/stdout, the same way a shell would spawn archsmith and read its stdout — except the process stays alive across many calls instead of exiting after one.
Tools: get_schema, render, validate, list_registries, get_registry (mirrors the CLI's own commands — same validate-before-render behavior, same family filter on get_registry). render defaults to embedFonts: false, keeping the normal agent path compact. Pass embedFonts: true deliberately when the exported SVG must carry the bundled Arimo font and render identically without installed fonts; the embedded font is subset to just the glyphs that diagram's text needs (see issue #55), so the size added scales with the diagram rather than a fixed cost — still worth opting into deliberately rather than by default, but no longer a blind ~40 KB tax regardless of content. A render still under 25,000 bytes of SVG comes back as one text content block; a larger one — a big diagram, or embedFonts: true on one — comes back as a resource_link instead, fetchable via resources/read, so the tool result itself never grows unbounded regardless of diagram size. This MCP-specific behavior does not change the renderer library or CLI, which continue to embed fonts by default and return the SVG directly. get_schema returns the same JSON Schema as the archsmith://schema resource below, as a tool — the connected model can call it on its own initiative before authoring an IR, without depending on the host client to surface a resource; validate/render point at it and at get_registry in their own descriptions, and again in the response when the IR is invalid.
Resources: archsmith://schema and one archsmith://registries/<name> per governed registry — lets an agent authoring an IR read the live, current schema/registries directly instead of working from a stale copy baked into a prompt. render also dynamically registers an archsmith://render/<id> resource for any render large enough to need one (see Tools above); it's not enumerable via resources/list — only reachable via the resource_link render itself returns — and is held in a small in-memory, bounded cache (the most recent 20 renders) rather than persisted, so it doesn't survive a server restart and older entries get evicted once a session renders past that cap.
Recommended authoring workflow for a connected agent: read the schema (get_schema) → read the relevant registries (get_registry) → construct an IR → validate → render.
For an inspectable real run of that complete workflow—including the original plain-English requirement, clarification exchange, published MCP configuration, privacy-reviewed tool sequence, final IR/SVG, and a published-action CI consumer—see the agent-authored architecture diagram example.
To connect it to an MCP host (e.g. Claude Desktop's claude_desktop_config.json):
{
"mcpServers": {
"archsmith": {
"command": "npx",
"args": ["-y", "@archsmith/mcp-server"]
}
}
}Working from a clone instead (e.g. to test a local change)? Point at the built entrypoint directly:
{
"mcpServers": {
"archsmith": {
"command": "node",
"args": ["/absolute/path/to/archsmith/packages/mcp-server/dist/index.js"]
}
}
}The GIF is a condensed presentation. The agent-authored example is the reproducible, inspectable evidence; any edited demo derived from such a run should link back to its retained artifacts.
An IR document is a JSON object with five columns, an optional legend, and optional notes. The schema is published at schema/latest/diagram-schema.json, with immutable versioned copies such as schema/0.3.5/diagram-schema.json. Use a versioned URL in committed documents for reproducible editor validation; the latest URL is intended for tooling that should follow the newest schema.
Name your file *.archsmith.json and SchemaStore gives you autocomplete and inline validation automatically in VS Code, JetBrains IDEs, and other SchemaStore-aware editors — no $schema line required. See packages/schema/README.md for the manual $schema fallback.
This is the actual minimal valid fixture from examples/:
{
"$schema": "https://ayeshlk.github.io/archsmith/schema/0.3.5/diagram-schema.json",
"schemaVersion": "0.3.5",
"title": "Minimal Example — Architecture",
"subtitle": "A minimal fixture proving the validation pipeline end to end",
"colorTheme": { "family": "standard" },
"columns": {
"inboundActors": {
"items": [
{ "title": "Web App", "dotColor": "purple", "descriptionLines": ["React SPA"] }
]
},
"ingress": { "gateway": { "label": "API Gateway", "sublabel": "Production Runtime" } },
"corePlatform": {
"deployedOn": "Production Runtime",
"subLayers": [
{ "registryId": "execution-and-capability", "rows": [[{ "title": "Backend Service", "descriptionLines": ["REST APIs"] }]] }
],
"systemsOfRecord": { "registryId": "systems-of-record", "items": [{ "title": "Primary DB", "descriptionLines": ["PostgreSQL"] }] }
},
"egress": { "gateway": { "label": "API Gateway", "sublabel": "Outbound M2M" } },
"externalSystems": {
"clusters": [
{ "name": "Shared Internal Services", "items": [{ "title": "Email Service", "dotColor": "teal", "descriptionLines": ["Notifications"] }] }
]
}
},
"legend": { "entries": [{ "colorToken": "green", "label": "Execution and Capability Layer" }] }
}The full schema (packages/schema/diagram-schema.json) and governed registries (packages/schema/registries/) define every field and every allowed color/sub-layer token — see packages/schema/README.md for the governance model. examples/ticket-booking/README.md is a richer, fully-featured reference document, and examples/README.md is the gallery index for additional fictional fixtures.
This is an npm workspaces monorepo — each package does one job, and only the layer above it knows the layer below exists:
Package | What it does |
The IR schema (JSON Schema draft 2020-12) plus governed registries (sub-layers, colors, icons). Versioned independently — adding a registry entry is a deliberate change-request, not a per-diagram decision. | |
Validates an IR against the schema/registries and renders it to SVG. Pure function, no I/O beyond reading its own bundled font, no LLM dependency. | |
| |
|
Questions, or something not working the way this README says it should? Open a GitHub issue. Report suspected vulnerabilities privately through the security policy, not through public issues.
Contributions are welcome — see CONTRIBUTING.md for how to build/test locally and, importantly, the governance rules around changing the schema or registries (this is what keeps the output a consistent house style rather than free-form per-diagram layout). Participation is governed by the Code of Conduct. If you're an AI coding agent, see AGENTS.md too. Planned work and open directions are tracked as GitHub issues — roadmap for bigger capability directions (new diagram notations, pluggable styles), narrower labels (schema, mcp-server, release) for everything else.
Returns the raw, current contents of a governed registry — the live source of truth for which colors/sub-layer types a diagram IR may use. This is governed vocabulary, not the IR's structural document contract; see get_schema for that. For 'colors' specifically, pass family to get just one color family instead of the whole registry.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| family | No | For the 'colors' registry only: restrict to a single family, e.g. 'standard'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It conveys that the read is raw, current, and a 'live source of truth' (freshness/read-only context), but never states permissions, whether reads are cached, rate limits, or the shape/size of what comes back. Adequate but incomplete for an unannotated 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-loaded with the core action and tightly packed, with sibling disambiguation and the family shortcut each getting a clause. Slightly dense wording ('raw, current contents') but no padding or redundancy.
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 should say more about what 'contents' look like (registry entry structure, whether icon/sub-layer entries differ from color entries). It covers identity and routing well but leaves the return payload largely unspecified for a two-parameter tool with no annotations.
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 50%: 'family' is documented in the schema, and 'name' is an enum whose values are largely self-explanatory. The description's note about passing 'family' for colors restates what the schema already says, and it mentions colors/sub-layers but omits the 'icons' value. Baseline 3 fits since the schema does most of the work.
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 ('returns the raw, current contents of a governed registry') and immediately distinguishes itself from the sibling get_schema by naming the difference (governed vocabulary vs. IR structural contract). An agent can pick this over get_schema 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?
Explicitly routes the agent: use this for governed vocabulary, use get_schema for the structural document contract, and use 'family' when only one color family is wanted. There is no guidance for list_registries or an explicit when-not, but the primary sibling disambiguation is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the ArchSmith diagram IR JSON Schema (draft 2020-12) — the structural contract a diagram IR document must satisfy. Call this, and get_registry for governed vocabulary, before authoring an IR.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that the tool is a read-only reference fetch with no side effects implied, and that the output is a schema (draft 2020-12). It does not describe output size, whether the schema is static or versioned, or how it is returned. Adequate but not rich.
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?
Two tight sentences with no waste, front-loaded with what is returned before the call-to-action. Some minor redundancy in restating what a JSON Schema is ('the structural contract...').
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 zero-param reference tool with no output schema or annotations, the description covers purpose, format, and when to call it. It could note that the schema is authoritative/static, but is largely 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?
Zero parameters, so the baseline of 4 applies. There is nothing for the description to add on parameters.
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 (Returns) and resource (ArchSmith diagram IR JSON Schema) and pins the draft version (2020-12). It also frames what the schema IS ('the structural contract a diagram IR document must satisfy'), which an agent can distinguish from siblings like validate and render.
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 says when to call it: 'Call this, and get_registry for governed vocabulary, before authoring an IR.' It names the paired sibling (get_registry) and the sequencing (before authoring), which is exactly the routing an agent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the governed registries (e.g. sub-layers, colors, icons) available via get_registry.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. 'Lists' implies a read-only operation, but the description does not explicitly state read-only safety, permission requirements, side effects, or pagination 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?
A single, front-loaded sentence with examples and a sibling reference. No wasted words and appropriately sized for a simple list 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 a zero-parameter list tool with no annotations and no output schema, the description adequately conveys purpose, examples of registries, and the relationship to get_registry. The return value (registry names) is implied.
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 tool has zero parameters, so the rubric baseline is 4. There are no parameter semantics for the description to add meaning 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?
States a specific verb ('Lists') and resource ('governed registries'), gives examples (sub-layers, colors, icons), and names the related sibling get_registry, distinguishing this discovery tool from the retrieval 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?
The phrase 'available via get_registry' implies this is a discovery step before calling get_registry, but there is no explicit when-to-use guidance, no named alternatives, and no exclusions. Usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validates then renders an ArchSmith diagram IR to a complete SVG document. Call get_schema and get_registry first to learn the required IR structure and governed vocabulary before authoring a document. Font embedding defaults to false to keep MCP responses compact; only opt in if the SVG must render portably without installed fonts — embedding adds a font subset sized to this diagram's own text, not a fixed cost, but it's still an added cost worth opting into deliberately. A render under 25,000 bytes is returned as one text content block; a larger one (e.g. a big diagram, or embedFonts:true on one) is returned as a resource_link instead, fetchable via resources/read, so the tool result itself never grows unbounded. Fails with the validation errors (isError: true) instead of rendering if the IR is invalid — never renders broken geometry from an invalid document.
| Name | Required | Description | Default |
|---|---|---|---|
| ir | Yes | The diagram IR document to render. | |
| embedFonts | No | Embed the bundled Arimo font for portable rendering, subset to just the glyphs this diagram's text needs (not the whole font). Default: false. |
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 well: it discloses the 25,000-byte threshold that switches the result from a text content block to a resource_link fetchable via resources/read, and that invalid IR fails with isError:true rather than emitting broken geometry. Embedding cost and the opt-in default are also made explicit.
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 core action, then prerequisites, then return-shape and failure semantics in a single dense paragraph with no filler topics. Minor redundancy in the embedFonts justification ('still an added cost worth opting into deliberately') costs it a point.
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?
No output schema exists, so the description properly explains return behavior (inline text vs resource_link and how to fetch it) plus the failure mode. For a 2-param tool with a nested free-form IR object, nothing an agent needs to invoke or interpret the call correctly 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 coverage is already 100%, so baseline is 3. The description goes beyond the schema's field text by framing embedFonts as a deliberate cost tradeoff (subset sized to this diagram's own text, not a fixed cost), which helps the agent decide rather than just describing the flag.
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 pipeline: validates an ArchSmith diagram IR and renders it to a complete SVG document. An agent can tell what it produces (an SVG) and from what (an IR) without opening the schema, and the scope is narrowed to ArchSmith diagrams rather than a generic renderer.
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 a concrete prerequisite flow (call get_schema and get_registry first to learn the IR structure and vocabulary) and conditional guidance for embedFonts (opt in only when portability without installed fonts is required). It does not explicitly state when to prefer this over the sibling validate tool, which is the only gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validates an ArchSmith diagram IR document against the schema and governed registries (sub-layers, colors). Call get_schema and get_registry first to learn the required structure and governed vocabulary before authoring an IR. Returns { valid, errors }.
| Name | Required | Description | Default |
|---|---|---|---|
| ir | Yes | The diagram IR document to validate. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It usefully discloses the return contract ({ valid, errors }) and that registries are consulted beyond the schema, but says nothing about side effects, error behavior, or whether validation is purely read-only — reasonable inference for a validator, but not stated.
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?
Three short sentences, each earning its place: what it validates, the prerequisite workflow, and the return shape. Front-loaded with the core action and no filler.
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 correctly compensates by naming the return fields { valid, errors }, and it points to get_schema/get_registry for the nested IR structure. What the errors array contains is left implicit, a minor gap for a tool whose input is an opaque nested object.
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 single 'ir' parameter is already documented as 'The diagram IR document to validate.' The description adds only that it is checked against schema and registries, which is supplementary rather than filling any semantic gap. 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 verb (validates) and resource (ArchSmith diagram IR document) plus the exact standards checked: schema and governed registries (sub-layers, colors). It also names sibling tools (get_schema, get_registry) so an agent can place it in the workflow without opening other schemas.
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 explicit ordering guidance: call get_schema and get_registry first, then author an IR and validate it. This tells the agent when to invoke validate relative to siblings, though it stops short of stating when validation is unnecessary (e.g., for already-validated IRs).
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.
v0.8.1get_registryget_schemalist_registriesrendervalidateScored across 5 tools
Each tool has a clearly distinct role: get_schema provides the structural contract, list_registries/get_registry provide governed vocabulary, validate checks conformance, and render produces SVG. The descriptions explicitly distinguish schema (structure) from registry (vocabulary) and clarify that render subsumes validation, preventing misselection.
Three tools use verb_noun (get_schema, list_registries, get_registry) while two use bare action verbs (validate, render). The split is logical—retrieval uses get/list, actions use bare verbs—but it is not a single uniform pattern, so it falls short of perfect consistency.
Five tools map cleanly onto the core workflow: discover the schema, discover registries, validate, and render. Each tool earns its place with no redundancy, fitting comfortably in the well-scoped 3-15 range.
The surface covers the full author-validate-render lifecycle, including registry listing and lookup, so agents can complete the primary task. Minor gaps exist: no example IR or starter template, and no alternative export formats or render-option introspection beyond what render's description mentions.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Immutable agent diagrams: create, edit, validate and render versioned diagrams over MCP.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
