This server turns ArchLang floor-plan source into drawings and helps inspect, validate, repair, and finish plans.
Compile .arch source or Plan JSON to SVG, ASCII text, Plan JSON, or PNG, including multi-storey plans, circulation overlays, accessibility metadata, and specific levels/widths.
Describe a plan’s facts without rendering: rooms, areas, doors, windows, circulation, zones, storeys, extents, and totals.
Lint and validate architectural soundness, strict checks, intended room adjacency graphs, and brief intent expectations.
Score how well a plan satisfies a brief’s intent JSON.
Repair and fix furniture placement or machine-applicable compile diagnostics.
Finish plans by furnishing rooms and adding sheet statements for export.
Suggest doors/windows for topology gaps, provide source completions, and generate playground/embed share links.
Write a floor plan as text. Get a precise, dimensioned drawing back.
No install: ArchLang app in ChatGPT or add https://mcp.archlang.uk/mcp as a claude.ai connector.
Paste this into any coding agent. The skills are listed on skills.sh: https://skills.sh/ChanMeng666/archlang
1. Run: npx -y skills add ChanMeng666/archlang --yes
2. Run: npx -y @chanmeng666/archlang spec (read it before writing anything)
3. Write my floor plan as plan.arch from this brief: <describe rooms, areas, adjacencies>
4. Run: npx -y @chanmeng666/archlang compile plan.arch -o plan.svg --json
then describe plan.arch --json, validate plan.arch --strict --json (same prefix); fix, recompile
5. Run: npx -y @chanmeng666/archlang finish plan.arch, then compile again to export.For MCP clients: claude mcp add archlang -- npx -y @chanmeng666/archlang-mcp.
https://github.com/user-attachments/assets/a60f3174-6a8c-4a42-b24a-fac030d39627
Related MCP server: Skopia
npx skills add ChanMeng666/archlangThen ask your coding agent:
Design a one-bedroom flat of about 54 m², with the front door on the north wall.
It writes the plan, compiles it and checks it. This one is 57 lines of text:
Click the drawing to open this exact plan in the playground. Change a number and it redraws.
Change one number, and one thing moves. Nothing else is redrawn.
The same source gives the same drawing, byte for byte.
An agent can check its own plan without ever looking at an image.
flowchart LR
B([Brief]) --> W[Write .arch]
W --> C{Compiles?}
C -->|no| F[Apply the fix<br/>the error carries] --> C
C -->|yes| V{Matches<br/>the brief?}
V -->|no| W
V -->|yes| O([SVG · DXF · PDF · PNG])Name the elements you want to keep with an id=, then ask the compiler whether an edit touched them. It exits 2 if one moved:
npx -y @chanmeng666/archlang impact new.arch --against old.arch --lock r_main,d_front,w_mainA worked example is on archlang.uk/edit-one-room. Starting from a photo or PDF? ArchLang does not read images, but your own assistant can: archlang.uk/from-an-image.
Each links to a short section with an example, on archlang.uk/whats-new, which also lists the version that brought it.
Quantities and takeoff: archlang takeoff plan.arch --format csv
Locked elements: archlang impact new.arch --against old.arch --lock shell,front
Wall status: status existing|demolish|new, demolition drawn dashed
Imperial lengths: 12ft6in
Review sheet: archlang preview plan.arch --review
Circulation overlay: archlang compile plan.arch --overlay circulation
Stacked storeys: keep stacked core on levels 1 2
Intent across storeys: archlang validate plan.arch --intent intent.json
What Plan JSON leaves out: archlang compile plan.arch -f json
More lint reports: W_WALL_END_SHORT, W_FURNITURE_ON_STAIR
L-shaped rooms: a rectilinear room polygon in walls from rooms
Turning stairs: stair id=s dir up width 1000 { flight … landing … flight … }
Window kinds: window fixed|casement|tilt|tilt_turn|sliding, door glazed_sliding
Corner windows: window on r.top at corner r.right width 1800
Furnishing every storey: archlang finish on a plan with level blocks
Labels in small rooms: a name that does not fit shrinks
Net area in the stamp: schedule rooms net
Sheet text: sheet text { total "SUMME" decimal "," }
Hidden sheet marks: north hidden, scale hidden, title hidden
One mirrored piece: furniture … mirror
Room floors: room … floor tile|paving|deck|concrete
More furniture: twenty new catalogued families
The rendered theme: theme rendered fills furniture symbols in a tint of their material
This page is all a person needs. Everything else is written for agents: clone the repo and point yours at AGENTS.md, or give it the whole language in one call:
npx -y @chanmeng666/archlang contextFull overview · Language reference · Release notes (installed: node_modules/@chanmeng666/archlang/CHANGELOG.md) · Contributing · MIT
ArchCanvas is a hosted app built on ArchLang. Built by Chan Meng.
Compile ArchLang .arch source (or a Plan-JSON object) to an SVG floor plan, or with format to a plain-text ASCII plan ("txt"), Plan JSON ("json") or an image ("png"). Format "json" returns the plan as an object, with schema naming its JSON Schema; passed back as plan_json it compiles to the same drawing, unless the plan uses a part of the language Plan JSON does not carry (sheet tables, styles, circular rooms, roofs, storeys, place, accessibility metadata). Returns the output plus diagnostics; a diagnostic usually carries a byte span with line/col and an E_/W_ code, and often a fix, sometimes one the fix tool can apply. Errors come back as data, never as exceptions: read diagnostics and correct the source. A multi-storey plan (level <n> { … }) returns the lowest storey in output and every storey in pages[] ({ level, name, output }); pass level to render just one. format "png" returns the usual result as text, then the drawing (the lowest storey, or level) as image content, as wide as width says; it needs the optional renderer @resvg/resvg-js, and without it the call returns ok:false with an error saying how to install it.
| Name | Required | Description | Default |
|---|---|---|---|
| level | No | Render only this storey of a multi-storey plan. An undeclared level is an error, not a guess. | |
| width | No | png only (any other format refuses it): the image width in pixels, clamped to 256-4096, and narrower for a tall plan so neither side exceeds 4096; default 1600. | |
| format | No | svg (default), txt (zero-dependency ASCII), json (Plan JSON, the shape `plan_json` takes) or png (an image; needs the optional renderer). | |
| source | No | ArchLang source (a `plan "…" { … }`). Provide this OR plan_json. | |
| overlay | No | Draw an opt-in circulation overlay (SVG only). | |
| plan_json | No | Plan JSON (RPLAN shape) as an alternative to `source`; converted to .arch then compiled. | |
| accessible | No | Emit <title>/<desc>/role/aria accessibility metadata (SVG only). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavior beyond the (already favorable) readOnly/idempotent annotations: errors are returned as data never exceptions, diagnostics carry byte spans, line/col, E_/W_ codes and often a fix, multi-storey plans return the lowest storey in `output` and all storeys in `pages[]`, and png requires the optional @resvg/resvg-js renderer with a specific ok:false failure mode. The Plan JSON round-trip limitations are called out explicitly.
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 verb, accepted inputs, and output formats before the caveats, and nearly every clause carries information. It is delivered as one dense run-on paragraph with heavy parenthetical nesting, which costs some scannability for an agent parsing it.
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 seven optional parameters, nested `plan_json`, and no output schema, the description still covers input alternatives, per-format behavior, return shape (`output`, `pages[]`, `diagnostics`), and the renderer dependency for png. An agent can call and interpret results without further information.
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; the description still earns extra credit by explaining that `plan_json` compiles to the same drawing and enumerating which language constructs (sheet tables, styles, circular rooms, roofs, storeys, `place`, accessibility metadata) do not survive the JSON round-trip. Most other parameter detail (width clamping, level errors) merely restates 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?
States a specific verb and resource (compile ArchLang `.arch` source or Plan JSON to an SVG/ASCII/JSON/PNG floor plan) and enumerates the output modes precisely. It is clearly distinguishable from siblings like lint, validate, fix, and score, which operate on rather than render the source.
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 concrete routing rules: provide `source` OR `plan_json`, `level` to render a single storey, `width` only for png and refused otherwise, and points to the `fix` tool for applicable fixes. It stops short of explicitly contrasting with `lint`/`validate` (check-only) as the alternative path, so it is strong but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the completion items in scope at a source byte offset: keywords, element names, ids and enum values, the same items an editor's language server offers. For structured or assisted authoring.
| Name | Required | Description | Default |
|---|---|---|---|
| at | Yes | Source byte offset to complete at. | |
| source | Yes | ArchLang source. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish that this is a read-only, idempotent, non-destructive, non-open-world operation. The description adds useful context by naming the kinds of completion items and comparing them to an editor language server, but it does not describe return shape, limits, or other behavioral details beyond that.
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 purpose is front-loaded in a single efficient sentence, followed by a short contextual tag. The trailing 'For structured or assisted authoring' is vague and adds little, keeping it just below top conciseness.
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 simple two-parameter, read-only tool with full schema coverage and annotations, the description is largely sufficient. It explains the kinds of items returned and the offset-based scope, though without an output schema it could be more explicit about the exact return structure.
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 both parameters are documented in the schema. The description reinforces the byte-offset semantics and source context, but it adds no syntax or format guidance beyond what the schema already provides, so the baseline of 3 is appropriate.
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 uses a specific verb ('List') and resource ('completion items in scope at a source byte offset') and even enumerates item categories. It does not, however, distinguish itself from likely sibling tools such as finish or suggest, so an agent still has to infer the boundary.
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 'For structured or assisted authoring' implies a usage context, but it gives no explicit when-to-use guidance, no exclusions, and no comparison to siblings like finish, suggest, or fix.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report a plan's facts without rendering, so you can check it against the brief without looking at an image. Returns rooms (area, bbox, adjacency, use, and the exact shape: floor_polygon for a room polygon, floor_circle for a room circle, whose area is exactly πR²), doors (what each connects), windows, circulation (walk distance, bottleneck width, detour), zones, storeys (levels[i] carries the same facts per floor) with the shafts that join them and which storeys stay reachable (vertical), the drawing extent (bbox, bbox_outer), freedom (which positions are hand-authored and which are derived), and totals.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ArchLang source. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, yet the description still adds substantial behavioral context: it enumerates exactly which fact categories come back (rooms, doors, windows, circulation, zones, storeys, bbox, freedom, totals) and clarifies derived vs. hand-authored data. Details like floor_circle area being exactly πR² and levels[i] carrying per-floor facts go well beyond what structured fields provide.
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 purpose is front-loaded in the first clause, before the long enumeration of returned facts. The single sprawling second sentence is dense and would read better as a list, but every element it names carries information an agent needs to interpret the response.
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 carries the burden of explaining return values and does so comprehensively — covering geometry keys, per-storey structure, reachability, bounding extents, and totals. An agent knows what to expect from the result without additional documentation.
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?
There is a single required parameter, `source`, and schema description coverage is 100%, so the schema already documents it ('ArchLang source.'). The description adds nothing about the source format, dialect, or constraints, so it only meets the baseline for a fully-covered 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?
States a specific verb and resource — 'Report a plan's facts without rendering' — and draws a clear line between fact extraction and image rendering. It does not, however, explicitly differentiate itself from sibling inspection tools like lint, validate, or score, so the agent must infer that this one is purely descriptive.
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 'so you can check it against the brief without looking at an image' implies a usage context (verifying facts rather than viewing geometry), but there is no explicit when-to-use/when-not-to-use statement and no named alternative among lint/validate/score/compile.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Complete a plan for export by adding what it lacks; run it once lint is clean. Two stages. furnish puts furniture, by room use, in each rectangular room that holds none, on every storey (a furnished room is never touched, and one that lacks a piece its use requires is named in unresolved with the missing pieces, not filled; placement is against wall / in <room> anchor, never absolute). sheet adds the sheet statements the plan lacks (paper, scale, dims auto, title, schedule rooms, legend), choosing the finest standard scale on the smallest sheet that holds the drawing. It fills only what is missing and deletes nothing; only runs one stage; reissue:true may replace paper/scale (only those) when the drawing does not fit them. Returns { ok, changed, changes, unresolved, source }; a plan that does not compile comes back untouched with ok:false, and every room left empty (its use has no furniture row or is unknown, or furnishing it would raise a new diagnostic) and every sheet statement left out is named in unresolved with the reason; a note with scope set (outside-table) asks nothing of you unless that room should hold furniture.
| Name | Required | Description | Default |
|---|---|---|---|
| only | No | Run only this stage. Default: `furnish`, then `sheet`. | |
| source | Yes | ArchLang source to finish. | |
| reissue | No | Allow `paper` and `scale` to be replaced when the drawing does not fit the authored sheet. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: it explains that furnished rooms are never touched, that rooms lacking required pieces are named in `unresolved` rather than filled, that it 'fills only what is missing and deletes nothing', and that a non-compiling plan comes back untouched with `ok:false`. It also discloses the special `reissue:true` exception (may replace `paper`/`scale` only), which is exactly the kind of mutation nuance annotations cannot convey, and does not contradict the readOnly/idempotent hints.
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?
Purpose is front-loaded in the first clause, and subsequent sentences are dense but information-bearing (stage semantics, unresolved behavior, return shape, edge cases). It is on the long side with some nested clauses, but little is wasted.
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 carries return values itself ({ ok, changed, changes, unresolved, source }) and covers edge cases: non-compiling input, empty rooms, omitted sheet statements, and `scope: outside-table` notes. Everything an agent needs to invoke correctly and interpret results 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?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `only` runs a single stage, `reissue:true` may replace `paper`/`scale` when the drawing does not fit, and it clarifies default sequencing. It doesn't add format/syntax details for `source`, but that is covered adequately by 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?
States a specific verb+resource: 'Complete a plan for export by adding what it lacks', then defines the two stages (furnish, sheet). It positions itself relative to `lint` ('run it once lint is clean') but does not explicitly distinguish itself from plausible siblings like `complete`, `repair`, or `fix`, which do similar-sounding work.
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?
'run it once `lint` is clean' gives a clear precondition for use, and the two-stage model plus `only` gives the agent a way to scope invocation. There are no explicit exclusions or direct comparisons against the overlapping siblings (`complete`, `repair`, `fix`), so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply the machine-applicable fixes attached to a plan's compile diagnostics and return the edited source. It corrects source-level faults (an opening off its wall becomes the attachment form, an out-of-range position is clamped, …); furniture geometry is repair's job. It runs at most 4 passes and rolls back a pass that raises the error count. unsafe:true also applies maybe-incorrect fixes. Returns { ok, passes, applied, skipped, source }.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ArchLang source to fix. | |
| unsafe | No | Also apply `maybe-incorrect` fixes (default: machine-applicable only). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial context beyond the annotations: at most 4 passes, rollback of any pass that raises the error count, the unsafe opt-in semantics, and the exact return shape { ok, passes, applied, skipped, source }. This is exactly the kind of non-obvious behavior annotations cannot convey, and it is consistent with readOnlyHint/idempotentHint.
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 in the first sentence and follows with scope, constraints, and return shape. Parenthetical examples ('an opening off its wall becomes the attachment form', 'an out-of-range position is clamped') are useful but slightly inflate the length.
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 only two flat parameters, no output schema, and full annotation coverage, the description still supplies the return-value shape, pass limits, and rollback semantics. Nothing an agent needs in order to call this 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 description coverage is 100%, so both `source` and `unsafe` are already documented. The description's mention of `unsafe:true` and `maybe-incorrect` fixes largely restates the schema rather than adding new syntax or edge-case meaning, so baseline 3 is right.
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: applies machine-applicable fixes from compile diagnostics and returns edited source. Explicitly separates itself from `repair` by saying furniture geometry is repair's job, so an agent can route between the two siblings without opening 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?
Names the alternative (`repair`) and the condition that selects it, and explains the `unsafe:true` opt-in for `maybe-incorrect` fixes. It does not state prerequisites such as running `compile`/`lint` first or the ordering relative to other siblings, so it falls short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Make two URLs that show a plan in the browser with nothing to install, for handing to a person. playground opens it in the hosted editor, rendered; embed draws it alone, for an iframe. The plan travels inside the URL, after the #, so it is never sent to a server and the URL carries nothing else. A plan that does not compile still gets links, and the page shows its diagnostics; ok says whether it compiles, and errors counts the errors when it does not. bytes is the size of the compressed plan in the URL.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ArchLang source. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only, idempotent annotations, it discloses key behavior: the plan is carried after the `#` and never sent to a server, the URL carries nothing else, non-compiling plans still get links, and the page shows diagnostics. It also explains the `ok`, `errors`, and `bytes` return values even though no output schema exists.
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 the core purpose and then adds only high-value details about URL fragment behavior and return fields. Every sentence earns its place with no 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 appropriately explains the returned `ok`, `errors`, and `bytes` fields. It also covers the privacy and fallback behavior needed to call and interpret 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?
The single `source` parameter is fully documented in the schema as ArchLang source, so the schema does the heavy lifting. The description does not add syntax or format guidance for `source`, which is acceptable at 100% coverage but limits credit here.
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?
It states a specific action (make two URLs) and resource (a plan shown in the browser), and explains the two link variants. It does not explicitly distinguish itself from siblings such as describe or compile, so it falls short of a 5.
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 clearly says the links are for handing to a person, and explains when to use `playground` versus `embed` for an iframe. It does not state when not to use the tool or name alternative sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List advisory architectural-soundness warnings (W_* codes) as data: unreachable room, windowless bedroom, too-narrow door, blocked doorway, furniture through a wall, circuitous path, and more. profile selects a ruleset ("residential-basic", "accessibility-advisory", …).
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ArchLang source. | |
| profile | No | Advisory ruleset name (default: the built-in ruleset). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds real value: results are advisory (not errors), returned as structured data with `W_*` codes, and the ruleset is switchable via `profile` with a built-in default.
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 dense sentences: the first front-loads what is returned and enumerates representative warning types; the second covers the only non-obvious parameter. 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?
For a two-parameter, read-only tool with no output schema, the description gives enough to call it correctly: source is ArchLang code, profile picks the ruleset. It stops short of describing result ordering or how warnings are keyed to locations, which would help an agent consume the output.
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 3 is the baseline. The description goes beyond the schema by naming concrete profile values ('residential-basic', 'accessibility-advisory') and clarifying that profile selects a ruleset, which the schema only describes generically as 'Advisory ruleset name'.
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?
Clearly states a specific verb and resource: lists advisory architectural-soundness warnings with `W_*` codes, plus concrete examples (unreachable room, windowless bedroom, blocked doorway). The 'advisory' framing implicitly separates it from the validation/score siblings, but no sibling is named explicitly.
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 word 'advisory' hints that this is a non-blocking check, but there is no explicit statement of when to use this versus `validate`, `score`, or the `fix`/`repair` pair that would presumably resolve the warnings. Usage must be inferred from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Correct furniture placement and return the corrected .arch source with a change log. It pushes furniture out of walls, doorways and door swings, separates overlapping pieces, moves fixtures that sit in the wrong room, and snaps floating pieces to walls. A piece it may not rewrite is listed in unresolved with the reason. It never adds doors or windows (that is a design choice); use suggest for those.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ArchLang source to correct. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations covering read-only, idempotent, non-destructive behavior, the description adds substantial context: it describes the specific corrections, reports unresolved pieces with reasons, returns a change log, and clarifies it never adds doors or windows. This goes well beyond what the 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 description is four focused sentences, front-loaded with the core action and return value. Each sentence adds useful detail without redundancy, and the exclusion is placed at the end where it naturally follows.
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 one well-documented parameter and no output schema, the description covers what the tool does, what it returns ('corrected .arch source with a change log'), how unresolved pieces are handled, and what it does not do. This is sufficient for an agent to invoke 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?
The input schema has full description coverage for the single 'source' parameter, so the schema carries the burden of parameter meaning. The description does not add any extra semantics about the parameter format or constraints, which is acceptable given the high coverage.
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 uses a specific verb ('Correct furniture placement') and explains the exact transformations performed, such as pushing furniture out of walls and snapping floating pieces. It explicitly distinguishes itself from the sibling tool 'suggest' for adding doors or windows.
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 clear exclusion ('never adds doors or windows') and names the alternative ('use suggest for those'). However, it does not differentiate itself from other likely siblings like 'fix' or 'lint', leaving some ambiguity about when to choose repair over those tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Measure how much of a brief's intent JSON a plan satisfies, without gating. Returns { ok, satisfied, total, score, subscores, violations }, where score is satisfied/total in [0,1] (an empty intent scores 1); call it across edits to watch a plan approach the brief. The intent's shape is the archlang://intent-schema resource. A malformed intent returns { ok:false, intentErrors } as data, never an exception.
| Name | Required | Description | Default |
|---|---|---|---|
| brief | Yes | A brief's intent JSON (shape: the archlang://intent-schema resource) to measure against. | |
| source | Yes | ArchLang source. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, it discloses the exact return shape, score semantics including the empty-intent edge case, malformed-intent error behavior as data rather than an exception, and the non-gating nature of the 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?
The definition is front-loaded with the purpose, then return semantics, usage context, schema pointer, and error behavior. Every sentence carries useful information with no 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?
Although there is no output schema, the description explains the return fields, score calculation, empty-intent behavior, and malformed-intent handling. Together with the full schema coverage, an agent has enough to call and interpret this 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 coverage is 100%, so both parameters are already documented. The description reinforces that `brief` is intent JSON with a referenced schema resource, but it adds little parameter-level syntax or semantics beyond the schema itself.
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 verb and resource: measuring how much of a brief's intent JSON a plan satisfies. The phrase 'without gating' implicitly distinguishes it from validate/lint-style siblings, but no sibling is named explicitly, so it falls short of a full 5.
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 clear usage context ('call it across edits to watch a plan approach the brief') and a when-not signal ('without gating'), so the agent knows this is for measurement rather than enforcement. It does not name alternatives such as validate or lint directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Suggest the doors and windows a plan's room graph needs, as data; nothing is applied. For a room with no path back, a building with no entrance, a bath reachable only through a bedroom, or a windowless bedroom, it returns ready-to-paste door/window statements with a rationale, for you to choose among and insert. Each names its wall by an authored id or a unique wall category, else by absolute at (x, y) coordinates. Door candidates avoid furniture in the door's approach; window candidates do not consider furniture.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ArchLang source. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive, but the description adds real substance beyond them: candidates come back as ready-to-paste statements with rationale, walls are referenced by authored id, unique category, or absolute coordinates, and door candidates avoid furniture in the approach while window candidates do not. Those are non-obvious output and selection traits an agent could not infer from the annotations.
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 distinction ('as data; nothing is applied') and no filler sentences. The second sentence is a long four-clause enumeration, but every clause is a distinct diagnostic case rather than 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?
There is no output schema, yet the description fully characterizes the return value: paste-ready door/window statements plus rationale, with the wall-naming variants spelled out. For a one-parameter advisory tool, an agent has everything needed to call it and interpret the result.
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?
There is a single parameter at 100% schema coverage, so the schema already says `source` is ArchLang source. The description adds only an indirect hint that the source must describe a plan's room graph; no syntax, size, or format guidance is offered.
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?
Specific verb plus resource: it suggests door/window statements for a plan's room graph, and states outright that 'nothing is applied'. That explicit advisory framing separates it from the mutating siblings repair/fix/link/complete without needing their 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?
It gives strong situational triggers (no path back, no entrance, bath only reachable through a bedroom, windowless bedroom) and tells the agent the follow-up flow: choose among candidates and insert them. It never names a specific sibling such as repair or fix as the alternative, so the routing is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check a plan in one pass without returning a drawing (parse, resolve and lint): the gate a plan passes before it ships. strict:true makes advisory warnings fail too. Optional graph checks the plan's interior-door adjacency against an intended room graph ({ room: [neighbours] }); a mismatch fails. Optional intent (a brief's expectations, shaped as the archlang://intent-schema resource describes) is checked against the plan: a missed gating assertion (room count, existence, area, total area, windows) fails, while adjacency and reachability are advisory and only score. A malformed intent returns { ok:false, intentErrors } as data, never an exception. Returns { ok, diagnostics, graph?, intent? }.
| Name | Required | Description | Default |
|---|---|---|---|
| graph | No | Intended interior-door adjacency: { room: [neighbour rooms] }. | |
| intent | No | A brief's intent JSON (shape: the archlang://intent-schema resource); gating assertions fail. | |
| source | Yes | ArchLang source. | |
| strict | No | Advisory warnings fail too. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only/idempotent annotations, the description discloses the consequences that matter: a graph mismatch fails, gating intent assertions fail while adjacency and reachability are only advisory, malformed intent returns `{ ok:false, intentErrors }` as data rather than throwing, and it never returns a drawing. This is materially more than the annotations provide.
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 a single dense paragraph that front-loads the core operation and then layers the optional behaviors. Every clause carries information, though the nested parentheticals and the long intent sentence make it slightly heavier than necessary.
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, but the description supplies the return shape (`{ ok, diagnostics, graph?, intent? }`) and explains the special data-return path for malformed intent. Combined with the behavioral and parameter detail, an agent has everything needed to call and interpret this 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 coverage is 100%, so the baseline is 3, but the description goes further by explaining what each optional parameter means for outcomes: strict raises warnings to failures, graph is checked against an intended room adjacency map, and intent is governed by a referenced intent-schema resource with gating versus advisory categories. That adds decision-relevant meaning beyond the schema field 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?
The description states a precise verb (check/validate), the resource (a plan), and the composite operation (parse, resolve and lint) in one pass, plus the distinguishing trait that it returns no drawing. That is enough to separate it from sibling tools such as compile, lint, or score.
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 clear context for the tool's role ('the gate a plan passes before it ships') and spells out the conditions for the optional modes: strict makes warnings fail, graph compares against intended adjacency, and intent checks a brief's expectations. It stops short of explicitly naming alternatives like lint or score, so no exclusions are stated.
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.1.0compilecompletedescribefinishfixlinklintrepairscoresuggestvalidateScored across 11 tools
Most tools have clearly distinct purposes, but a few pairs require careful reading: fix vs repair both edit source, lint vs validate both report diagnostics, and score vs validate both check intent. The descriptions explicitly delineate these boundaries, so misselection is unlikely but not impossible.
All tool names are single lowercase imperative verbs with no mixed conventions or underscores. The pattern is predictable throughout the set.
Eleven tools is well within the appropriate range for a language tooling server covering authoring, validation, repair, finishing, and sharing. Each tool appears to earn its place without obvious redundancy.
The surface covers the full lifecycle: completion, compile, validate, lint, fix, repair, suggest, finish, describe, score, and link. Minor gaps like a dedicated format/explain tool are not critical, as compile and diagnostics cover those needs.
Floor plans in real mm: doors, windows, fixtures; validate, render, elevations, sections, storeys.
Headless CAD engine & MCP server for 2D/3D drafting, solids, DXF/SVG export, and automation.
Architecture compiler for AI code. 11 tools, 92 actions, 872 Lean4 proofs, 100/100 self-cert.
Write, check and render parametric laser-cutting designs in KerfScript, as SVG or DXF.
