Provides read-only access to Archicad projects via the Tapir Add-On, enabling discovery, inspection, and spatial orientation of project data.
Click on "Install 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., "@archicad-tapir-mcp what's in the current Archicad project?"
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.
An agent-friendly, read-only-first MCP bridge for Archicad and the Tapir Add-On.
PRD.md — product requirements and architecture direction.
docs/PROJECT_STATE.md — current implementation,
verification, gaps, and next work.
docs/DECISIONS.md — architectural decision log.
docs/EXPERIMENTS.md — live Archicad/Tapir evidence.
docs/TARGET_CONTEXTS.md — sticky per-task target
binding and nickname contract.
docs/OPENCODE.md — OpenCode as the local end-to-end MCP
agent harness (operator runs OpenCode; OpenCode must invent the MCP sequence).
AGENTS.md — mandatory maintenance protocol for agent sessions.
The current read-only MCP surface includes:
archicad_discover — low-level endpoint diagnostics.
archicad_instances — human-readable project cards and stable runtime IDs.
archicad_bind — sticky target context from a project hint, candidate, or
witnessed foreground intent.
archicad_capabilities — in-band workflow and coverage guidance.
archicad_capture_context — fresh semantic observation with focus parts.
archicad_inspect — progressive expand of snapshot-scoped handles.
archicad_spatial_map — character-grid orientation for a sheet/marquee/zone.
archicad_read — up to 20 safe low-level reads; returns/revalidates context.
Related MCP server: Archicad MCP Server
Node.js 24+
npm
Windows production environment
Archicad on the same Windows machine
Tapir installed in Archicad
The current repository can still be developed and tested from WSL2, but the production MCP process is intended to run natively on Windows.
npm install
npm run build
npm testStart Archicad completely, then run:
npm run probeDiscovery tries, in order:
ARCHICAD_HOST when explicitly configured for development;
127.0.0.1, which is the normal Windows production route;
the default WSL2 gateway when running the development probe from WSL.
To force the Windows host during WSL development:
ARCHICAD_HOST=172.20.112.1 ARCHICAD_PORTS=19723-19743 npm run probeThe WSL gateway/LAN route is development-only. Do not make production behavior depend on it.
Run the production service from Windows PowerShell:
npm run build
node C:\path\to\archicad-tapir-mcp\dist\index.jsExample local MCP configuration:
{
"mcpServers": {
"archicad": {
"command": "node",
"args": [
"C:\\path\\to\\archicad-tapir-mcp\\dist\\index.js"
]
}
}
}The server writes protocol messages only to stdout and diagnostics to stderr.
OpenCode is the local agent used to prove MCP tool descriptions are enough for
discovery and observation. You play the engineer: give a task in plain language.
OpenCode must choose the MCP calls. Full runbook, prompts, and pass/fail rules:
docs/OPENCODE.md.
cd C:\Users\psxcode\Documents\Archicad
npm run build
opencode mcp list
opencode run -m lmstudio/openai/gpt-oss-20b --auto --title "e2e-smoke" "List open Archicad projects using only Archicad MCP tools."Requires OpenCode (WinGet), LM Studio with a loaded model, and Archicad/Tapir on
localhost. Record new live outcomes in docs/EXPERIMENTS.md.
archicad_read accepts a requests array with:
product_info
tapir_version
project_info
current_window
selection_summary
selected_elements
all_elements
Every first operation may include a project hint or explicit instanceId. When
the evidence is strong, the server binds and returns an opaque contextId in the
same call. Reuse that context in later operations. With multiple weak or tied
candidates, the server returns project cards and asks the agent to select a card
or have the user foreground the intended Archicad; it never guesses from Z-order
alone.
This version makes no changes to an Archicad project. Mutation tools, context snapshots, event indexing, rendering, and semantic operations will be added only after the live connection and Tapir response shapes are recorded and tested.
Create or replace a sticky target context. Prefer a project hint for saved projects, an explicit instanceId from candidate cards when the semantic relation is clear, or useRecentForeground only after the user explicitly foregrounded 'this Archicad'. If ambiguous, show candidates and ask the user to foreground the intended Archicad. Carry the returned contextId in every later operation.
| Name | Required | Description | Default |
|---|---|---|---|
| hint | No | ||
| timeoutMs | No | ||
| instanceId | No | ||
| confirmAlias | No | Durable nickname explicitly confirmed by the user. Never pass the existing project name/display name/path. Allowed only with instanceId. | |
| useRecentForeground | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate no read-only/idempotent behavior; description adds that it creates/replaces context and the returned contextId should be carried in later operations, disclosing mutation and usage pattern.
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?
Four sentences, front-loaded with primary purpose, followed by clear preference hierarchy. 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?
Covers parameter use and ambiguous cases, but lacks error handling or failure scenarios. Adequate given no output schema.
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 low (20%), but the description explains when to use each parameter (hint, instanceId, useRecentForeground) and adds constraints for confirmAlias, compensating for 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?
Description clearly states it 'creates or replaces a sticky target context' and distinguishes from siblings by listing preferred methods (project hint, instanceId, useRecentForeground).
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 provides decision criteria: prefer project hint for saved projects, instanceId from candidate cards, useRecentForeground only after user foregrounded. Also advises to show candidates if ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use only when unsure how Archicad tools compose or when a capture reports degraded capabilities. Returns the observation hierarchy, recommended call order, handle lifetime, and current correctness rules. It reads no project data.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, confirming safety. Description adds 'It reads no project data' and describes return contents, enhancing transparency without contradiction.
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 sentences front-loaded with usage condition, output list, and safety statement. Every sentence is informative and no redundant 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?
For a zero-parameter, no-output-schema tool, the description fully covers purpose, usage, and behavior. It leaves no ambiguity about what the tool does and when 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?
No parameters exist, baseline 4. Description adds value by explaining what the tool returns and when to use it, beyond the schema which is empty.
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 'use only when' and clearly states the resource: 'observation hierarchy, recommended call order, handle lifetime, and current correctness rules'. It distinguishes from siblings by specifying when to use it (unsure how tools compose or degraded capabilities).
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 'Use only when' with two clear scenarios. It implies when not to use (when not unsure), but does not explicitly name alternative tools, though context from sibling names provides some guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
START HERE after binding when you need to understand words such as here, this, selected, or inside the dashed marquee. Pass target.contextId from archicad_bind; do not bind again by hint. A capture records stories (floors/namespaces) that own sheet_island and outside-sheet drawing_island / loose_fragment regions, plus active selection, marquee, and 2D viewport as independent focus parts. On FloorPlan, default operator intent is the active story (summary.activeStoryHandle): if the operator did not name a floor, stay there. Read stories[] and regionRoles first (sheets and WIP clusters are siblings). Then focusResolution — use preferredRegionHits/preferredResolution for here/this marquee; regionHits remain full multi-story XY truth. For focus questions, report preferred hits first; cards with no matching focusRelationships are not hits. Use maxRegionCards=0 when focus resolution alone is enough. Use current_database when enclosing sheet and nearby cluster/table context matters; selection is a faster exact-workset mode and may omit its surrounding sheet. Keep snapshotId and expand only relevant handles. Detected sheets and title-block fields remain candidates, not ground truth.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Default current_database: relates marquee/selection/viewport to enclosing sheets, outside-sheet clusters, and tables. Use selection for a faster exact-workset read of selected BIM/drafting elements (Roof, Window, …); members retain type/bounds/floorIndex even when Tapir type-specific details are unsupported. Selection may omit enclosing sheets. | current_database |
| target | No | ||
| timeoutMs | No | ||
| explicitBounds | No | Optional disconnected focus rectangles in Archicad model coordinates. They supplement native selection/marquee/viewport as separate focus parts; they do not crop sheet reconstruction. | |
| maxRegionCards | No | Initial card page size. First page reserves slots for outside-sheet clusters when present. Use 0 for a compact focus-only answer; page regions later by inspecting the returned snapshotId. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses detailed behavioral traits: what a capture records (stories, selection, marquee, viewport), how focus resolution works (preferredRegionHits), and caveats like 'Detected sheets... remain candidates, not ground truth' and 'selection may omit enclosing sheets.' No contradictions with 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?
The description is well-structured and front-loaded with the critical starting instruction. It is dense but not verbose, with each sentence adding value. A slight reduction in length could improve conciseness, but the current structure effectively guides the agent.
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 no output schema and a complex domain, the description covers the main aspects: what the tool captures, how to interpret results (focus resolution, region roles), and parameter use cases. It could mention error handling or limits, but overall it is sufficiently complete for an agent to use 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 description adds significant meaning beyond the input schema, especially for scope (explaining trade-offs of current_database vs selection) and maxRegionCards (using 0 for focus-only). With 60% schema coverage, the description compensates well, though a few parameters like timeoutMs and explicitBounds have limited additional context.
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 states the tool's purpose: 'Observe the current Archicad context' and explicitly explains it is the starting point after binding to resolve ambiguous references like 'here', 'this', 'selected', or marquee. This sets it apart from sibling tools like archicad_read or archicad_discover, which serve different functions.
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 provides explicit usage guidance: 'START HERE after binding' and 'Pass target.contextId from archicad_bind; do not bind again by hint.' It distinguishes when to use selection vs current_database scopes and explains when to set maxRegionCards to 0. Alternatives are implied but the guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Low-level diagnostic discovery of Archicad endpoints. Prefer archicad_instances for agent routing and human-readable project cards.
| Name | Required | Description | Default |
|---|---|---|---|
| host | No | Archicad host. Omit to try localhost and the detected WSL2 Windows gateway. | |
| ports | No | ||
| timeoutMs | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint as true or false. The description adds context about it being 'low-level diagnostic' but does not disclose further behavioral traits such as what endpoints are discovered or any side effects.
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 sentences, both essential, with no wasted words. It is front-loaded and concise.
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 low-complexity diagnostic tool with no output schema, the description provides purpose and usage guidance but lacks detail on what the function returns and parameter semantics, leaving gaps for effective agent usage.
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 low (33%), and the description does not mention any parameters or add meaning beyond the schema. It fails to compensate for the missing parameter 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 clearly states it is a 'Low-level diagnostic discovery of Archicad endpoints' and distinguishes itself from the sibling 'archicad_instances' by noting the latter is preferred for routing and human-readable cards.
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 explicitly says to prefer 'archicad_instances' for agent routing and human-readable cards, indicating when not to use this tool. However, it does not fully elaborate on when to use this tool beyond diagnostics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Expand a snapshot, story, region, element-set, or detected-structure handle returned by archicad_capture_context. Always pass the matching snapshotId because handles are snapshot-scoped. Passing handle=snapshotId pages more region cards. A story_* handle returns that floor's region cards. A title_block handle returns source text candidates and inferred metadata; a table handle returns reconstructed cells with optional text angles, titleCandidates, parentRegionHandle, sections, and left-to-right fragments when a schedule is layout-split. An elements_* handle returns paged primitives. For a region, use detailLevel=card first. Recapture instead of treating an old snapshot as current project truth.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| handle | Yes | snapshotId, story handle, region handle, elementHandle, or childStructures handle from that snapshot. | |
| offset | No | ||
| snapshotId | Yes | Immutable observation ID returned by archicad_capture_context. | |
| detailLevel | No | card |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the base safety is known. The description adds rich behavioral detail: paging behavior for specific handle types (story_*, elements_*), return contents for title_block and table handles, and the warning against stale snapshots. This goes well beyond 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?
The description is a single paragraph of 7 sentences, which is reasonably concise but lacks clear structure (e.g., bullet points or sections). It front-loads the purpose but then mixes details about different handle types without visual separation, making it somewhat dense.
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 the complexity (multiple handle types, pagination, no output schema), the description covers many behavioral aspects: what each handle returns, paging hints, and a warning about snapshot staleness. However, it does not explain pagination semantics (limit/offset) for all handle types, which is a gap.
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 low (40%), but the description compensates by explaining how to use handle values (snapshotId, story_*, title_block, table, elements_*) and what each returns. It also advises on detailLevel usage. For limit and offset, it adds nothing beyond the schema, but the overall parameter meaning is significantly enhanced.
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 specifies the verb 'expand' and the resource type 'snapshot, story, region, element-set, or detected-structure handle returned by archicad_capture_context', clearly identifying the tool's function and scope. It distinguishes from siblings by focusing on handle expansion rather than general reading or discovery.
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 provides explicit context: always pass snapshotId, use detailLevel=card first for a region, and recapture instead of using old snapshots. It implies usage after archicad_capture_context but does not explicitly state when not to use or name alternatives, though the sibling list provides that context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Refresh the background registry and return concise project cards with stable runtime instance IDs, project identity, selection summary, aliases, and focus evidence. Use when a target is ambiguous; do not ask the user for a port or PID.
| Name | Required | Description | Default |
|---|---|---|---|
| timeoutMs | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is clear. The description adds context about refreshing the background registry, which is a non-destructive side effect, and details the output fields. This goes beyond annotations but is not extensive, earning a 4.
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 two concise sentences that front-load the core purpose and important usage guidance. Every word is meaningful 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?
Given the simple nature of a listing tool and the absence of an output schema, the description adequately details the output content (project cards with IDs, identity, summary, aliases, focus evidence). It covers the essential behavioral and output information, making it complete for agent use.
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 one parameter (timeoutMs) with no description (0% coverage). The description does not mention this parameter or add any semantic meaning beyond the schema defaults and constraints. Given the low coverage, the description should compensate but fails to do so.
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 title and description clearly state the tool lists routable Archicad projects with specific output details (IDs, identity, summary, aliases, focus evidence). It distinguishes from siblings by specifying 'Use when a target is ambiguous,' implying this tool identifies which instance to use, unlike other tools like archicad_bind or archicad_capabilities.
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 explicitly states when to use this tool ('when a target is ambiguous') and what not to do ('do not ask the user for a port or PID'), providing clear guidance on when it is appropriate versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Low-level diagnostic reads, not the drawing-understanding workflow. Prefer archicad_capture_context and archicad_inspect for observation; never call all_elements to validate a semantic snapshot. Run up to 20 isolated reads and reuse target.contextId. all_elements/selected_elements return a count by default; request raw only when GUIDs are explicitly required and bounded. Ambiguity returns candidate cards instead of guessing. Direct host/port is development-only.
| Name | Required | Description | Default |
|---|---|---|---|
| host | No | Archicad host. Omit to try localhost and the detected WSL2 Windows gateway. | |
| port | No | ||
| target | No | ||
| requests | Yes | ||
| timeoutMs | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint, idempotentHint, and openWorldHint annotations, the description adds behavioral details: default return count for all_elements/selected_elements, raw mode caution, ambiguity handling, and development-only host/port usage. No contradictions with 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?
The description is highly concise: a few sentences that front-load the purpose, followed by usage rules and constraints. Every sentence adds value without 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?
Given the tool's complexity (5 params, nested requests, no output schema) and good annotations, the description covers key behavioral context: max 20 reads, context reuse, default summary mode, ambiguity handling, and development-only host/port. It could briefly mention return value structure or error handling, but the description is largely complete for an agent to use 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 only 20%, but the description adds meaning by explaining when to use target.contextId, that requests can be up to 20, and that host/port are for development only. However, it does not explain each action's parameters or provide detailed semantics for the complex nested requests object.
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 states it is for 'low-level diagnostic reads' and explicitly distinguishes it from the 'drawing-understanding workflow.' It contrasts with sibling tools like archicad_capture_context and archicad_inspect, making its purpose unambiguous.
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 provides explicit usage guidance: prefer archicad_capture_context and archicad_inspect for observation, never call all_elements to validate a semantic snapshot, run up to 20 isolated reads, reuse target.contextId, and use raw mode only when GUIDs are explicitly needed. It also notes that direct host/port is development-only and that ambiguity returns candidate cards instead of guessing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a Doom-style text map for orientation. Default zone is the snapshot 2D viewport on the active story (D-025) when zone is omitted or empty. Agents may still pass regionHandle (sheet/cluster; scoped to that region's story), explicitBounds, or focusKind (marquee/selection/viewport). Viewport/marquee/selection/bounds maps paint active-story regions and floor-filtered BIM by default. Resolution is the long-side cell count (default 32, max 48); the short side follows the zone aspect ratio. Drafting lines, fills, text, BIM stamps (walls, columns, windows, doors, roofs, zones), and detected overlays are painted with priority overwrite. Sheet frames use # only for confirmed sheets (title/production or inner trim); drawing_island / loose_fragment outlines use - and | (same as drafting). Roof stamps use glyph R from live bounds even when Tapir type-specific roof details are still unsupported. Pass snapshotId from archicad_capture_context. Prefer regionHandle when the operator names a specific sheet or cluster. This is a secondary navigation aid; inspect handles for exact geometry.
| Name | Required | Description | Default |
|---|---|---|---|
| zone | No | Map zone. Omit or leave empty to use the current viewport on the active story. Pass at most one of regionHandle, explicitBounds, or focusKind. | |
| target | No | ||
| enrichBim | No | When true and a bound target is available, fetch live Zone/Fill/Wall/Column/Window/Door/Roof bounds inside the map zone, filtered to the active story floorIndex when known. | |
| timeoutMs | No | ||
| resolution | No | Cell count along the longer world edge. The shorter edge is derived from the zone aspect ratio. | |
| snapshotId | Yes | Immutable observation ID from archicad_capture_context. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, idempotentHint=true, openWorldHint=false. The description adds behavioral details beyond annotations: painting rules, priority overwrite, resolution derivation, specifics about sheet frames and roof stamps, and that roof stamps use glyph R even when type-specific details are unsupported.
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 with information and front-loaded with the main purpose and default scenario. Each sentence adds specific value, but could be slightly more concise with paragraph breaks. No wasted sentences, but length could be trimmed.
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 6 parameters, nested objects, and no output schema, the description covers default behavior, zone options, resolution, BIM enrichment, painting rules, and usage hints. It lacks explicit description of return format (e.g., multi-line string) but 'Doom-style text map' and 'character-grid map' provide enough context for an AI agent.
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 given as 67%. The description adds meaning beyond the schema: explains resolution as cell count along longer edge with aspect ratio derivation, default and max; for zone, clarifies what happens when omitted and cautions about passing at most one option; for target, adds 'Opaque sticky context' and usage rules. Compensates for lower 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 title and description clearly state the tool returns a character-grid text map for spatial orientation, specifying default zone and inputs like regionHandle, explicitBounds, or focusKind. It distinguishes from sibling tools by mentioning it's a secondary navigation aid and referencing snapshotId from archicad_capture_context.
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 guidance: default zone is the viewport when zone is omitted; 'Prefer regionHandle when the operator names a specific sheet or cluster'; and 'This is a secondary navigation aid; inspect handles for exact geometry' which advises when to use alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a distinct purpose: discovery, instance listing, capabilities checking, binding, low-level reading, context capturing, inspection, and spatial mapping. Descriptions provide clear guidance on when to use each, minimizing ambiguity.
All tools share the 'archicad_' prefix, but the verb/noun pattern is inconsistent: some are verbs (discover, bind, read, inspect), some are nouns (instances, capabilities, spatial_map), and one is verb_noun (capture_context). This mixed style reduces predictably.
With 8 tools, the server is well-scoped for its purpose—interacting with Archicad through discovery, binding, context capture, inspection, and spatial mapping. No tool seems redundant, and the count feels appropriate.
The tool surface covers the core workflow: discover instances, bind to one, capture context, inspect elements, and navigate via spatial map. Minor gaps might include lack of update/delete operations, but these align with the read-oriented design.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
An MCP server that provides access to Testiny projects, test cases and test runs
MEOK ABCI Bridge MCP — read-only Tendermint / Cosmos blockchain query for agents. Built-in registry
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Read-only MCP server over the APIs.io catalog — discover APIs, providers, tags & artifacts.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/psxcode/archicad-tapir-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
