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., "@ArchiMate MCP Server create a business actor named 'Customer'"
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 MCP (Model Context Protocol) server that enables LLMs to work with ArchiMate models stored in coArchi2 repositories. The server design follows the ArchiMate 3.2 specification structure, making it intuitive for LLMs to select appropriate layers, elements, and relationships.
Full ArchiMate 3.2 Support: All element types across Motivation, Strategy, Business, Application, Technology, and Implementation & Migration layers
Relationship Validation: Enforces valid ArchiMate relationships per the specification
LLM-Friendly Design: Layer-specific tools with enumerated element types guide correct usage
coArchi2 Compatible: Reads and writes model.archimate XML files
ArchiMate Exchange Format: Import/export using the standard ArchiMate Open Exchange Format
Multiple Export Formats: SVG, PNG, Mermaid diagrams, Markdown documentation, and interactive HTML decks
Audit Logging: Track all model operations with NDJSON audit logs
Impact Analysis: Analyze dependencies and impacts of architecture changes
Related MCP server: ArchiMate MCP Server
Node.js 18+
npm
cd archimate-mcp-server
npm install
npm run buildclaude mcp add archimate -- npx -y archimate-mcp-server@latestClone and build, then add to Claude Code:
git clone https://github.com/thijs-hakkenberg/archimate-mcp.git
cd archimate-mcp
npm install
npm run build
claude mcp add archimate -- node $(pwd)/dist/index.jsVerify it was added:
claude mcp listRemove if needed:
claude mcp remove archimateAdd to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"archimate": {
"command": "node",
"args": ["/path/to/archimate-mcp-server/dist/index.js"]
}
}
}Tool | Description |
| Open a model from a coArchi repository |
| Save the current model |
| Create a new empty model |
Tool | Description |
| List elements (optionally filtered by layer/type) |
| Get element details with relationships |
| Search elements by name pattern |
Tool | Element Types |
| Stakeholder, Driver, Assessment, Goal, Outcome, Principle, Requirement, Constraint, Meaning, Value |
| Resource, Capability, ValueStream, CourseOfAction |
| BusinessActor, BusinessRole, BusinessCollaboration, BusinessInterface, BusinessProcess, BusinessFunction, BusinessInteraction, BusinessEvent, BusinessService, BusinessObject, Contract, Representation, Product |
| ApplicationComponent, ApplicationCollaboration, ApplicationInterface, ApplicationFunction, ApplicationInteraction, ApplicationProcess, ApplicationEvent, ApplicationService, DataObject |
| Node, Device, SystemSoftware, TechnologyCollaboration, TechnologyInterface, Path, CommunicationNetwork, TechnologyFunction, TechnologyProcess, TechnologyInteraction, TechnologyEvent, TechnologyService, Artifact, Equipment, Facility, DistributionNetwork, Material |
| WorkPackage, Deliverable, ImplementationEvent, Plateau, Gap |
| Grouping, Location |
Tool | Description |
| Create a relationship (validates against ArchiMate spec) |
| List relationships |
| Get valid relationship types between element types |
Supported Relationship Types: Composition, Aggregation, Assignment, Realization, Serving, Access, Influence, Association, Triggering, Flow, Specialization
Tool | Description |
| List all diagram views |
| Create a new view |
| Add an element to a view; connections to on-canvas peers are auto-drawn (opt out with |
| Manually add a connection — normally unnecessary since |
Tool | Description |
| Update element name/documentation |
| Delete element and its relationships |
| Delete a relationship |
Tool | Description |
| Get element counts by layer |
| Analyze element dependencies |
Tool | Description |
| Import model from ArchiMate Open Exchange XML |
| Export model to ArchiMate Open Exchange XML |
Tool | Description |
| Generate Mermaid diagram syntax from model or view |
| Export view as SVG or PNG image |
| Export model as Markdown documentation |
| Export model as interactive HTML deck |
Tool | Description |
| Enable/disable audit logging, set log path |
| Read recent audit log entries |
URI | Description |
| Catalog of all ArchiMate element types |
| Catalog of relationship types |
| Current model summary |
Once connected, you can ask Claude to:
Open the ArchiMate model at /path/to/my-model
Create a new Business Actor called "Customer" with documentation "External customer"
Create an Application Component called "Order Service"
Create a Serving relationship from "Order Service" to "Customer"
Show me all elements in the Application layer
What relationships are valid between ApplicationComponent and BusinessProcess?
Do an impact analysis on the "Order Service" component
Export the model as Markdown documentation to /path/to/docs.md
Generate a Mermaid diagram for the Business layer
Export the main view as an SVG to /path/to/diagram.svg
Create an interactive HTML deck of the architectureGenerate Mermaid flowchart syntax that can be rendered in Mermaid-compatible viewers:
flowchart TB
subgraph Business["Business Layer"]
BA1["Customer"]
BP1["Order Process"]
end
subgraph Application["Application Layer"]
AC1["Order Service"]
end
AC1 -->|Serving| BP1Export diagram views as scalable SVG or rasterized PNG images with:
Color-coded elements by layer
ArchiMate notation
Relationship lines with appropriate arrows
Generate comprehensive documentation including:
Model overview with statistics
Elements grouped by layer
Relationship details
Embedded Mermaid diagrams for views
Create an interactive single-file HTML presentation with:
Tab navigation by layer
Element cards with relationship details
Search functionality
Light/dark theme support
Embedded SVG diagrams
All model operations can be logged to an NDJSON file for auditing:
{"timestamp":"2024-01-15T10:30:00.000Z","event":"archimate_create_business_element","action":"create","elementType":"BusinessActor","elementId":"id-123","elementName":"Customer","success":true,"durationMs":5}Configure via environment variable:
export ARCHIMATE_AUDIT_LOG=/path/to/audit.ndjson # Set log path
export ARCHIMATE_AUDIT_LOG=disabled # Disable loggingThe server validates relationships against the ArchiMate 3.2 specification. Invalid relationships are rejected with helpful error messages:
Error: Assignment is not a valid relationship between DataObject and BusinessActor
Suggestions: Realization, Serving, Association, Flowarchimate-mcp-server/
├── src/
│ ├── index.ts # MCP server entry point
│ ├── model/
│ │ ├── types.ts # ArchiMate type definitions
│ │ ├── parser.ts # XML model parser
│ │ └── writer.ts # XML model writer
│ ├── relationships/
│ │ └── validation.ts # Relationship validation
│ ├── exporters/
│ │ ├── mermaid-exporter.ts # Mermaid diagram generation
│ │ ├── svg-exporter.ts # SVG/PNG diagram rendering
│ │ ├── markdown-exporter.ts # Markdown documentation
│ │ └── html-deck-exporter.ts # HTML presentation deck
│ ├── exchange/
│ │ ├── exchange-reader.ts # ArchiMate Exchange import
│ │ └── exchange-writer.ts # ArchiMate Exchange export
│ └── audit/
│ └── logger.ts # Audit logging system
├── dist/ # Compiled output
├── package.json
├── tsconfig.json
└── vitest.config.ts # Test configurationnpm test # Run tests
npm run test:watch # Run tests in watch mode
npm run test:coverage # Run tests with coverageMIT
Manually add a connection (line/arrow) between two diagram objects in a view. Normally unnecessary - archimate_add_to_view auto-draws connections for all relationships it finds between the new element and existing on-canvas elements. Use this tool only to: (a) restore a connection after calling archimate_add_to_view with auto_connect: false, or (b) add a connection that was not auto-drawn because one endpoint was not yet in the view. Both diagram objects must already be in the view.
| Name | Required | Description | Default |
|---|---|---|---|
| view_id | Yes | ID of the view | |
| relationship_id | Yes | ID of the relationship to visualize | |
| source_diagram_object_id | Yes | ID of the source diagram object (from archimate_add_to_view response) | |
| target_diagram_object_id | Yes | ID of the target diagram object (from archimate_add_to_view response) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the manual nature, the conditions for use, and the prerequisite. While it doesn't cover error handling or potential side effects (e.g., if connection already exists), it provides sufficient behavioral context for an add operation.
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 concise—three sentences. The first sentence states the core action, followed by context on when it's needed. No wasted words, and information is front-loaded.
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 specificity and lack of output schema, the description is complete. It explains purpose, usage scenarios, prerequisites, and distinguishes from the main sibling tool. No critical information 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 100%, so baseline is 3. The description adds value by explaining the relationship_id as 'the relationship to visualize' and noting that source and target IDs come from the archimate_add_to_view response. This enriches understanding beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Manually add a connection (line/arrow) between two diagram objects in a view.' It distinguishes itself from the sibling tool 'archimate_add_to_view' which auto-draws connections, making its purpose specific and non-overlapping.
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 tells when to use this tool: only when auto_connect is false or when a connection wasn't auto-drawn because one endpoint wasn't in the view. It also states a prerequisite: both diagram objects must already be in the view. This provides clear usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add an element to a diagram view. Connections for relationships between this element and any element already in the view are drawn automatically - you do not need to call archimate_add_connection_to_view for them. The response lists every connection that was auto-drawn in autoConnectedRelationships.
| Name | Required | Description | Default |
|---|---|---|---|
| view_id | Yes | ID of the view | |
| element_id | Yes | ID of the element to add | |
| x | No | X position (default: auto) | |
| y | No | Y position (default: auto) | |
| width | No | Width (default: 120) | |
| height | No | Height (default: 55) | |
| auto_connect | No | Auto-draw diagram connections for relationships between this element and on-canvas peers (default: true). Set to false only if you want to place the element without any connections and add them manually. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description bears full burden. It discloses auto-connection behavior and response content (autoConnectedRelationships). It does not mention potential side effects like duplicate adds, but the behavior is adequately described for a view mutation 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?
Two sentences, no filler. The action and key behavior are front-loaded. Every sentence serves a purpose.
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, it mentions the response includes autoConnectedRelationships. It doesn't specify if the element must exist, but that's implied by element_id. Overall sufficient for a straightforward add-to-view operation.
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%, but the description adds value by explaining auto_connect's purpose and stating that x/y default to auto, width=120, height=55, and that the response lists auto-drawn connections. This meaningfully extends 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?
The description clearly states it adds an element to a diagram view and distinguishes itself from the sibling tool 'archimate_add_connection_to_view' by explaining auto-connection behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says you do not need to call archimate_add_connection_to_view for relationships, and the auto_connect parameter provides guidance on when to set it to false. This gives clear when-to-use and when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Configure audit logging for model operations
| Name | Required | Description | Default |
|---|---|---|---|
| enabled | No | Enable or disable audit logging | |
| log_path | No | Path to the audit log file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does not disclose whether this is a destructive operation, if it requires special permissions, or what the scope of the configuration change is.
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?
Single sentence, no waste. Could be slightly more structured, but it is appropriately concise for a simple 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 2-param configuration tool with no output schema, the description is too minimal. It does not explain the effect of enabling/disabling or how the configuration persists.
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 baseline is 3. The description adds no additional meaning beyond the schema; both parameters are already described well in 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?
The description 'Configure audit logging for model operations' clearly states the verb (configure) and resource (audit logging), and adds context with 'for model operations'. It distinguishes from the sibling tool 'archimate_get_audit_log' which retrieves logs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, no prerequisites, and no context about the effect of enabling/disabling audit logging.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an Application layer element (Chapter 9). Use for application components, services, and data objects.
| Name | Required | Description | Default |
|---|---|---|---|
| element_type | Yes | Type of application element: ApplicationComponent (software unit), ApplicationCollaboration (components working together), ApplicationInterface (access point), ApplicationFunction (automated behavior), ApplicationInteraction (collective behavior), ApplicationProcess (sequence of behaviors), ApplicationEvent (state change), ApplicationService (exposed behavior), DataObject (structured data) | |
| name | Yes | Name of the element | |
| documentation | No | Optional documentation/description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as idempotency, prerequisites (e.g., model must be open), or side effects. For a creation tool, this is a significant gap.
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, no wasted words. Action verb is front-loaded. Efficient and to the 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?
The description is minimal but covers basic purpose. However, given the simplicity of the tool and high schema coverage, it adequately informs the agent. Missing guidelines and behavioral details prevent a higher score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add meaning beyond the schema; it repeats concepts already covered by the enum 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 'Create an Application layer element' and specifies usage for application components, services, and data objects. It distinguishes from sibling tools (e.g., create_business_element) by explicitly naming the layer.
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 a clear context ('Use for application components, services, and data objects') but lacks explicit exclusions or references to alternatives. It implies usage but does not specify when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a Business layer element (Chapter 8). Use for actors, processes, services, and business objects.
| Name | Required | Description | Default |
|---|---|---|---|
| element_type | Yes | Type of business element: BusinessActor (entity performing behavior), BusinessRole (responsibility), BusinessCollaboration (working together), BusinessInterface (access point), BusinessProcess (sequence of behaviors), BusinessFunction (collection of behavior), BusinessInteraction (collective behavior), BusinessEvent (state change), BusinessService (exposed behavior), BusinessObject (concept/information), Contract (agreement), Representation (perceptible form), Product (collection of services) | |
| name | Yes | Name of the element | |
| documentation | No | Optional documentation/description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only says 'Create a Business layer element' without disclosing side effects, authorization needs, behavior on duplicates, or what is returned. This is minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the main purpose. It could be slightly more detailed but remains efficient.
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 of 13 element types and no output schema, the description lacks completeness. It does not mention return values, error handling, or prerequisites, leaving significant gaps for the 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 100% and includes detailed enum descriptions. The description adds context like 'actors, processes, services' which complements the schema, but does not significantly enhance understanding beyond 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?
The description clearly states it creates a Business layer element and gives examples like actors, processes, services, and business objects. This distinguishes it from sibling tools for other layers, but the list of allowed types is extensive and not fully enumerated.
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 provides some guidance by saying 'Use for actors, processes, services, and business objects', implying when to use this tool. However, it lacks explicit exclusions or alternative suggestions for other layers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a composite element (Chapter 4). Use for grouping and locations.
| Name | Required | Description | Default |
|---|---|---|---|
| element_type | Yes | Type of composite element: Grouping (aggregate concepts), Location (place where things are located) | |
| name | Yes | Name of the element | |
| documentation | No | Optional documentation/description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only states the tool creates an element, but does not describe side effects, required permissions, return behavior, or whether it modifies an existing model. This is insufficient for an agent to understand the tool's impact.
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 very short, consisting of one sentence and a short clause. It front-loads the core action ('Create a composite element'). However, the parenthetical '(Chapter 4)' is cryptic and does not earn its place, slightly reducing 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?
The tool has 3 parameters, no output schema, and no annotations. The description does not explain return values, whether the model must be open, or how to interpret the result. Given the complexity of creating an element and the many sibling tools, the description is too minimal to be fully 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?
The input schema has 100% description coverage and includes detailed descriptions for each parameter (e.g., element_type explains 'Grouping (aggregate concepts), Location (place where things are located)'). The tool description reinforces this with 'Use for grouping and locations', adding context beyond the schema. According to guidelines, high schema coverage yields a baseline of 3, but the description adds meaningful value, justifying a 4.
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 'Create a composite element (Chapter 4). Use for grouping and locations.' It identifies the verb (Create) and resource (composite element) and mentions the two enum types (Grouping, Location). However, it does not clearly differentiate from sibling element creation tools (e.g., archimate_create_application_element) beyond the enum values, and the 'Chapter 4' reference is obscure.
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 'Use for grouping and locations' gives some context for when to use this tool (creating Grouping or Location elements). However, it provides no explicit guidance on when not to use it or alternatives among the many sibling tools for creating other element types.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an Implementation & Migration layer element (Chapter 12). Use for work packages, deliverables, and architecture plateaus.
| Name | Required | Description | Default |
|---|---|---|---|
| element_type | Yes | Type of implementation element: WorkPackage (series of actions), Deliverable (result of work), ImplementationEvent (state change), Plateau (stable architecture state), Gap (difference between plateaus) | |
| name | Yes | Name of the element | |
| documentation | No | Optional documentation/description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only states the action (create) without mentioning side effects, permissions, or safety. For a creation operation, this is a significant gap.
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 concise sentence that immediately conveys the purpose and intended use. Every word is valuable, and the key information (layer, element types) is front-loaded.
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 simplicity of the tool (3 parameters, no output schema), the description provides adequate context about the layer and element types. However, it lacks behavioral guidance, which slightly reduces completeness. No output schema means return values are not explained, but that is acceptable for a create 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%, with all three parameters described. The description adds a list of element types but does not provide additional semantic meaning beyond what the schema already offers for the enum values. Baseline score 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?
Description clearly states creating an Implementation & Migration layer element, referencing Chapter 12 and listing element types (work packages, deliverables, plateaus). This distinguishes it from sibling tools like create_business_element or create_technology_element, which cover other layers.
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 'Use for work packages, deliverables, and architecture plateaus' provides clear guidance on when to use the tool. However, it does not explicitly state when not to use it or mention alternative tools, though the layer-specific naming implies exclusion of other layers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new empty ArchiMate model with standard folder structure
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the new model | |
| path | Yes | Path where to save the model |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the model is empty and includes a standard folder structure, but does not explain side effects (e.g., whether it saves automatically, overwrites existing files) or required application state.
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 clear sentence with no unnecessary words. While concise, it could include additional brief context without becoming verbose. It is appropriately front-loaded but just a touch lean.
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, the description does not mention return value (e.g., model ID or success indication). For a create tool with two simple parameters, the description is adequate but could be more complete by hinting at next steps (e.g., 'Use this before adding elements or views').
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 baseline is 3. The description adds no extra meaning beyond the schema's parameter descriptions ('Name of the new model', 'Path where to save the model'), only incrementing the context of 'standard folder structure'.
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 action ('Create a new empty ArchiMate model') and the resource ('with standard folder structure'), distinguishing it from sibling tools like archimate_create_view (creates a view within a model) and element creation tools.
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 implies usage when starting a new model but does not explicitly state when to use this tool versus alternatives like opening an existing model (archimate_open_model) or creating views/elements. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a Motivation layer element (Chapter 6). Use for stakeholders, goals, requirements, etc.
| Name | Required | Description | Default |
|---|---|---|---|
| element_type | Yes | Type of motivation element: Stakeholder (person/role with interests), Driver (motivation condition), Assessment (analysis result), Goal (desired end state), Outcome (end result), Principle (general intent), Requirement (specific need), Constraint (limitation), Meaning (interpretation), Value (worth/importance) | |
| name | Yes | Name of the element | |
| documentation | No | Optional documentation/description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as side effects (e.g., auto-save), permission requirements, or constraints like duplicate checks, leaving the agent with limited insight.
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, front-loading the purpose and providing immediate clarity without unnecessary words.
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 creation tool with three parameters and no output schema, the description covers the basic concept but lacks context about the Motivation layer's role or post-creation behavior (e.g., no return value mentioned).
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 100% description coverage, with element_type enum annotated for each value. The description adds only a 'Chapter 6' reference, so it does not significantly enhance meaning beyond 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?
The description clearly states the tool creates a Motivation layer element and lists examples like stakeholders, goals, and requirements, which distinguishes it from sibling create tools targeting other layers.
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 implies usage for Motivation layer elements but provides no explicit guidance on when to use this tool versus alternatives like archimate_create_business_element or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a relationship between two elements. Validates against ArchiMate specification.
| Name | Required | Description | Default |
|---|---|---|---|
| relationship_type | Yes | Type of relationship: Composition (consists of), Aggregation (combines), Assignment (allocates responsibility), Realization (creates/implements), Serving (provides functionality), Access (reads/writes), Influence (affects), Association (unspecified link), Triggering (causes), Flow (transfers), Specialization (is a kind of) | |
| source_id | Yes | ID of the source element | |
| target_id | Yes | ID of the target element | |
| name | No | Optional name/label for the relationship | |
| access_type | No | For Access relationships: type of access | |
| influence_modifier | No | For Influence relationships: strength modifier |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description is expected to disclose behavioral traits. It mentions validation but does not clarify what happens on validation failure (error/rollback), whether the operation is reversible, or any side effects. The lack of detail about mutation behavior is a significant gap.
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 extremely concise with two sentences, no superfluous information, and effectively front-loads the core purpose. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description omits critical context: return value (e.g., the created relationship object), error handling, validation specifics (e.g., which relationship types are valid for which element pairs), and behavior for optional parameters. Given the complexity of relationship creation and the absence of an output schema, this lack of detail hinders correct invocation.
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 covers 100% of parameters with descriptions, so the tool description adds no additional meaning. The baseline score of 3 is appropriate as the schema does the heavy lifting, and the description fails to clarify parameter interdependencies (e.g., access_type only relevant for Access type).
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 verb 'Create' and the resource 'relationship between two elements', distinguishing it from sibling tools like archimate_list_relationships or archimate_delete_relationship. The additional note about validation against the ArchiMate specification adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., archimate_add_connection_to_view). The description implies its use for creating relationships but does not mention prerequisites, exclusions, or scenarios where other tools are more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a Strategy layer element (Chapter 7). Use for capabilities, resources, and strategic planning.
| Name | Required | Description | Default |
|---|---|---|---|
| element_type | Yes | Type of strategy element: Resource (owned asset), Capability (ability to do something), ValueStream (sequence creating value), CourseOfAction (strategic approach/plan) | |
| name | Yes | Name of the element | |
| documentation | No | Optional documentation/description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It indicates creation but does not disclose side effects, required context (e.g., open model), or limitations. Adequate but minimal.
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, front-loaded with the main action and additional context. No wasted words.
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 creation tool with 3 parameters and no output schema or annotations, the description is fairly complete. It could mention model context but is sufficient given sibling tool patterns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description adds no extra meaning beyond the schema. Baseline score 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 clearly states it creates a Strategy layer element, specifying the layer and mentioning related concepts (capabilities, resources, strategic planning). This distinguishes it from sibling tools for other layers.
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 says 'Use for capabilities, resources, and strategic planning,' implying when to use it. It does not explicitly exclude when not to use or mention alternatives, but sibling tool names provide context for layer-specific usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a Technology layer element (Chapter 10). Use for nodes, devices, infrastructure, and physical elements.
| Name | Required | Description | Default |
|---|---|---|---|
| element_type | Yes | Type of technology element: Node (computational resource), Device (physical IT resource), SystemSoftware (infrastructure software), TechnologyCollaboration (working together), TechnologyInterface (access point), Path (link between elements), CommunicationNetwork (connects devices), TechnologyFunction (collection of behavior), TechnologyProcess (sequence of behaviors), TechnologyInteraction (collective behavior), TechnologyEvent (state change), TechnologyService (exposed behavior), Artifact (data/software file), Equipment (physical machines), Facility (physical structure), DistributionNetwork (transport network), Material (physical matter) | |
| name | Yes | Name of the element | |
| documentation | No | Optional documentation/description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It only states a creation action but does not mention side effects, persistence, or whether the created element is returned. Transparency is minimal.
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, front-loaded sentence that conveys the essential purpose without unnecessary words. It is concise and well-structured for quick comprehension.
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 creation tool with no output schema, the description covers the basic purpose and scope but omits details about return values or post-creation behavior. It is minimally adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter having a description in the schema. The tool description adds no new meaning beyond the schema values, so the baseline score 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 clearly states the action ('Create'), the resource ('Technology layer element'), and provides examples ('nodes, devices, infrastructure, and physical elements'). It distinguishes this tool from sibling tools by specifying the ArchiMate technology layer.
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 implies usage for technology infrastructure elements but lacks explicit guidance on when not to use it or comparisons with sibling tools like archimate_create_application_element.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new diagram view
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the view | |
| viewpoint | No | Optional viewpoint type (e.g., Layered, Organization, Application) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description does not disclose behavioral traits like whether it overwrites existing views, requires permissions, or has side effects. The action 'create' implies mutation, but no further detail.
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?
Single sentence with clear subject and action. Front-loaded and free of extraneous information. Could be slightly more detailed but remains efficient.
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 role in creating a view, missing details like whether a model must already exist, impact on existing views, or the structural context (e.g., view belongs to a model). No output schema, so description alone is insufficient.
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 covers both parameters (name, viewpoint) with descriptions. Description does not add new meaning beyond the schema, but schema itself provides adequate baseline for a simple create action.
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 'Create a new diagram view' clearly states the verb (Create) and resource (diagram view). While not explicitly distinguishing from siblings, it is distinct enough as other create tools target model elements, not views.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this vs alternatives such as archimate_create_model or other element creation tools. No context about prerequisites like an open model.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an element and its associated relationships
| Name | Required | Description | Default |
|---|---|---|---|
| element_id | Yes | ID of the element to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It mentions deletion cascades to relationships but lacks details on reversibility, side effects (e.g., removal from views), or error conditions. The burden is high and unmet.
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 sentence with no wasted words, frontloading the key action and resource. However, it could be slightly more informative without losing 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?
Given the simplicity of the tool (one param, no output schema, no annotations), the description should explain return value, success indication, or preconditions. It lacks these details, leaving the agent under-informed.
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% for the single parameter element_id, and the tool description adds no additional meaning beyond what the schema already provides. Baseline score 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 clearly states the action 'Delete' and the target 'an element and its associated relationships', distinguishing it from sibling tools like archimate_delete_relationship which only deletes a single relationship.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., archimate_delete_relationship for deleting a relationship without the element). The description does not mention prerequisites or scenarios where deletion is not appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a relationship
| Name | Required | Description | Default |
|---|---|---|---|
| relationship_id | Yes | ID of the relationship to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but fails to disclose behavioral traits such as permanence, cascading effects, or required permissions. The single sentence adds no behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one short sentence), but it sacrifices substance. While not verbose, it is too minimal for a deletion tool, lacking important context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides no information about return values, side effects, or operation outcomes. For a destructive action, this is critically incomplete 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 coverage is 100% with a description for relationship_id. The tool description adds no additional meaning beyond what the schema already provides, meeting the baseline for 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 'Delete a relationship' clearly identifies the action and resource, but it essentially restates the tool name and does not differentiate from sibling tools like archimate_delete_element. It is minimally adequate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., archimate_delete_element). There is no mention of prerequisites or context for deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export a diagram view as SVG or PNG image
| Name | Required | Description | Default |
|---|---|---|---|
| view_id | Yes | ID of the view to export | |
| output_path | Yes | Path to save the image file (use .svg or .png extension) | |
| format | No | Output format (default: detected from file extension) | |
| width | No | Image width in pixels (optional) | |
| height | No | Image height in pixels (optional) | |
| background_color | No | Background color (default: #ffffff) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It only describes the action without disclosing behavioral traits such as side effects (e.g., file creation), permissions needed, or whether it modifies the model. Limited transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is extremely concise and front-loaded with the key action. No wasted words.
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?
Despite full parameter coverage in schema, the description lacks context about prerequisites (e.g., open model, view existence), output format behavior, or error handling. The tool has 6 parameters and no output schema, requiring more guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters. The description adds no additional meaning beyond what the schema provides, so baseline score 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 clearly states the tool exports a diagram view as SVG or PNG image, specifying the verb and resource. It distinguishes from other export tools by focusing on diagram views, but does not explicitly mention sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like export_exchange or export_mermaid. The description only states what it does without context of appropriate usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export the current model to ArchiMate Open Exchange Format XML
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to save the exchange XML file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description omits behavioral traits like file overwriting, validation, or required prior steps (e.g., model saving). The single sentence does not compensate for the lack of 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, front-loaded sentence that efficiently conveys the tool's purpose with no wasted words.
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 export with a single parameter, the description is minimally adequate but lacks details on output or error handling, and doesn't address the variety of sibling export tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a well-described path parameter. The tool description adds no additional meaning beyond the schema, so a 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 clearly states the action (Export) and the resource (current model to ArchiMate Open Exchange Format XML), distinguishing it from sibling export tools like archimate_export_diagram.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as archimate_export_diagram or archimate_export_markdown. No context or exclusions provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export the model as an interactive HTML deck with tabs and search
| Name | Required | Description | Default |
|---|---|---|---|
| output_path | Yes | Path to save the HTML file | |
| title | No | Title for the HTML deck (default: model name) | |
| theme | No | Color theme (default: light) | |
| include_search | No | Include search functionality (default: true) | |
| embed_diagrams | No | Embed SVG diagrams instead of Mermaid (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden. It states the tool exports a model, suggesting a read-only operation, but doesn't disclose potential side effects, performance constraints, or prerequisites. The minimal disclosure limits transparency but doesn't mislead.
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, efficient sentence that conveys the core functionality without verbose or redundant content. Every word contributes to the purpose, achieving high 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?
Given the lack of output schema and annotations, the description should cover prerequisites (e.g., model must be open) and output behavior (e.g., file size). It does not address these, leaving the agent with insufficient context for a 5-parameter 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 baseline is 3. The description adds no extra parameter meaning beyond what the schema already provides (e.g., 'output_path', 'theme'). It does not elaborate on parameter usage or formatting, so no added value.
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 verb 'Export' and the resource 'model as an interactive HTML deck with tabs and search'. This distinguishes it from sibling tools like 'archimate_export_diagram' (single diagram) and 'archimate_export_markdown' (text), making the 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 implies usage: when an interactive HTML deck is needed. However, it doesn't explicitly contrast with siblings nor state when not to use. The sibling names provide implicit context, but direct guidance is missing, earning a 4 for clear but non-exclusive context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export the model as Markdown documentation
| Name | Required | Description | Default |
|---|---|---|---|
| output_path | Yes | Path to save the Markdown file | |
| include_views | No | Include views section (default: true) | |
| include_diagrams | No | Embed Mermaid diagrams in output (default: true) | |
| include_relationships | No | Include relationship details for each element (default: true) | |
| include_properties | No | Include element properties (default: false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosure. It only states the action (export) and format (Markdown) without mentioning side effects, safety behavior (read-only or mutation), file system implications, or output characteristics. Critical behavioral context is missing.
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 6-word sentence, which is highly concise and front-loaded. However, for a tool with 5 parameters and many siblings, it might be slightly too sparse, but it avoids any unnecessary 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?
Given the complexity (5 parameters, no output schema, no annotations) and the presence of multiple sibling export tools, the description is insufficient. It does not clarify the output structure, how it differs from other Markdown-like exports, or that it requires a file path. The tool's role in the workflow is underdescribed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add any extra meaning beyond what the schema already provides for each parameter. It merely lists the action without enriching parameter semantics.
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 'Export the model as Markdown documentation,' using a specific verb and resource. It distinguishes itself from sibling export tools (e.g., archimate_export_diagram, archimate_export_exchange, archimate_export_mermaid, archimate_export_html_deck) by specifying the output format.
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 no guidance on when to use this tool versus the many sibling export tools (e.g., archimate_export_mermaid, archimate_export_html_deck). No context about scenarios, prerequisites, or exclusions is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate Mermaid diagram syntax from the model or a specific view
| Name | Required | Description | Default |
|---|---|---|---|
| view_id | No | Optional: ID of a specific view to export (exports full model if not specified) | |
| direction | No | Diagram direction (default: TB for top-to-bottom) | |
| include_labels | No | Include relationship labels in diagram (default: false) | |
| layer_filter | No | Filter to specific layers (e.g., ["Business", "Application"]) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states 'generate' but does not explicitly disclosed that the tool is non-destructive or read-only. It lacks behavioral details about side effects or safety.
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 sentence, front-loaded with the main action, and contains no unnecessary words 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?
For a simple export tool with 4 optional parameters and no output schema, the description is adequate. However, it could mention the output format (Mermaid string) and that it is non-destructive. Minor 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 100% and each parameter already has detailed descriptions. The tool description does not add new semantic information beyond the schema, so baseline score 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 clearly states the verb 'generate' and the resource 'Mermaid diagram syntax', and distinguishes between two modes: full model or specific view. It is specific and not a tautology.
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 implies usage for generating Mermaid syntax, but does not explicitly compare it with sibling tools like archimate_export_diagram or archimate_export_markdown, nor states when to use this tool vs alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for elements by name pattern (case-insensitive regex)
| Name | Required | Description | Default |
|---|---|---|---|
| pattern | Yes | Name pattern to search for (regex supported) | |
| layer | No | Optional layer filter |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the key behavioral detail of case-insensitive regex matching, which is valuable. However, it does not specify return format, pagination behavior, performance implications, or whether the search is confined to certain element types beyond the optional layer filter.
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 efficient sentence, avoiding unnecessary words. It is front-loaded with the core action. Minor improvement could be to separate the case-insensitive behavior more prominently, but current form is good.
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 2 parameters and no output schema, the description covers the essential searching purpose. However, it lacks details about the return value (e.g., list of element IDs or names), error handling, or performance notes. A new user might need to experiment to understand the full behavior.
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 baseline is 3. The description restates the parameter concepts but adds no additional detail beyond what the schema already provides (e.g., regex support is already in schema description). It does not explain regex syntax or layer enumeration values.
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 verb ('Search') and resource ('elements'), specifies the search criterion ('name pattern') and key behavioral detail ('case-insensitive regex'). It distinguishes from sibling tools like 'archimate_list_elements' (which lists all without pattern filtering) and 'archimate_get_element' (which retrieves a single element by ID).
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 implies usage for pattern-based searching but does not explicitly state when to use this tool versus alternatives like 'archimate_list_elements' or 'archimate_get_element'. No exclusions, prerequisites, or comparison with siblings are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read recent entries from the audit log
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of entries to return (default: 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It mentions 'recent entries' but does not clarify read-only nature, authentication needs, or whether the tool affects the audit log state. This is insufficient for a tool with no 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 concise sentence that is front-loaded with the verb and resource. It contains no extraneous words or repetition.
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 absence of an output schema, the description should explain what fields the audit log entries contain (e.g., timestamp, user, action). It does not, making the tool's return value unclear for an 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 coverage is 100%, so the single parameter 'limit' is fully described in the schema. The description adds no additional meaning beyond the schema, thus baseline score 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 'Read recent entries from the audit log' clearly states the verb (Read) and resource (audit log), distinguishing it from sibling tools like archimate_configure_audit which focuses on configuration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as when to use archimate_configure_audit or other read tools. Context for appropriate usage is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific element including its relationships
| Name | Required | Description | Default |
|---|---|---|---|
| element_id | Yes | The ID of the element to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; the description does not disclose behavioral traits such as read-only nature, side effects, or permissions. 'Detailed information' and 'relationships' are vague.
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?
One short sentence conveying the core purpose with no wasted words.
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 retrieval tool with one param and no output schema, the description covers basic purpose but lacks details like what 'detailed information' includes (e.g., properties, relationships) or any constraints.
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 schema already fully describes the single parameter (element_id). The description adds nothing beyond the schema, meeting baseline for 100% 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 clearly states the tool retrieves detailed information and relationships for a specific element, distinguishing it from siblings like archimate_list_elements or archimate_find_elements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., list_elements, find_elements, impact_analysis) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get valid relationship types between two element types (helps understand what connections are permitted)
| Name | Required | Description | Default |
|---|---|---|---|
| source_type | Yes | Source element type | |
| target_type | No | Target element type (optional - shows all valid targets if omitted) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description only states what the tool returns without disclosing behavioral traits such as read-only nature, permissions needed, or side effects. The description does not add context beyond the basic function.
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?
Single sentence that is clear and front-loaded with the main action. No wasted words, though it could be structured with more detail in a second sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has low complexity with 2 simple parameters and no output schema. The description explains the purpose and mentions behavior when target_type is omitted. However, it lacks details about the return format or potential errors, relying on the 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 100%, so the baseline is 3. The description adds no additional parameter information beyond the schema. The optionality of target_type is mentioned, which matches 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?
The description clearly states the verb 'Get', the resource 'valid relationship types', and the context 'between two element types'. It effectively distinguishes from sibling tools like archimate_list_relationships and archimate_create_relationship.
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 implies usage for understanding permitted connections but does not explicitly state when to use this tool versus alternatives like archimate_list_relationships or archimate_create_relationship. No exclusions or alternative mentions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze dependencies and impact of an element
| Name | Required | Description | Default |
|---|---|---|---|
| element_id | Yes | ID of the element to analyze | |
| direction | No | Direction of relationships to analyze | |
| depth | No | How many levels deep to analyze (default: 2) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It does not disclose whether the analysis is read-only, requires permissions, or what the output format is. Only states the basic action.
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?
Single short sentence, no fluff, but it could be more informative without sacrificing 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?
Given the complexity of impact analysis with direction and depth parameters and no output schema, the description is too brief. Does not explain return values or default behavior, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. Tool description adds little beyond the schema; it does not clarify the meaning of direction or depth further. Baseline 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?
Description clearly states the tool analyzes dependencies and impact of an element, using a specific verb and resource. It distinguishes well from sibling tools like create, delete, export, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as archimate_get_element or archimate_find_elements. Does not mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import an ArchiMate model from Open Exchange Format XML file
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to the .xml exchange file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral transparency. It fails to disclose important traits such as whether the import overwrites existing models, requires an open session, or handles duplicate IDs. The description is too brief for a potentially destructive operation.
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 sentence of 12 words, with no unnecessary information. It is perfectly concise and front-loaded with the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only one parameter and no annotations. The description adequately states the purpose but lacks details on import behavior (e.g., merge vs replace, error handling). For a simple tool, it is minimally complete but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the parameter 'path' described as 'Path to the .xml exchange file'. The description adds 'Open Exchange Format XML file', which provides mild context beyond the schema but does not significantly enhance understanding.
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 verb 'Import' and the resource 'ArchiMate model', and specifies the format 'Open Exchange Format XML file'. This distinguishes it from siblings like 'archimate_export_exchange' which performs the opposite operation.
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 no guidance on when to use this tool versus alternatives, such as 'archimate_open_model' or other creation tools. No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a summary of elements by layer
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must carry full burden. It only states 'Get a summary of elements by layer' without disclosing behavior like read-only status, performance, or what 'summary' entails (e.g., counts, hierarchical structure).
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 sentence with no wasted words. It could be more informative without violating conciseness, but it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description does not explain the return value or structure of the summary, and with no output schema, the agent has insufficient context to know what to expect. Important for a no-parameter 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?
The input schema has zero parameters, and schema description coverage is 100%. The description adds no parameter details, but with no parameters, the baseline of 4 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 states the verb 'Get' and the resource 'summary of elements by layer', clearly distinguishing it from sibling tools like 'archimate_list_elements' which provide raw lists. However, the lack of title and brevity reduces it from 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?
No guidance on when to use this tool over alternatives, such as 'archimate_list_elements' or 'archimate_find_elements'. The context of use is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List elements in the model, optionally filtered by layer or type
| Name | Required | Description | Default |
|---|---|---|---|
| layer | No | Filter by ArchiMate layer | |
| element_type | No | Filter by specific element type (e.g., BusinessActor, ApplicationComponent) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It indicates a read operation but lacks details on side effects, authorization, rate limits, return format, or pagination. Adequate but not exhaustive.
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 concise sentence (13 words) that front-loads the action. 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?
The description covers the basic purpose and filters, but lacks details on return format, ordering, pagination, or the fact that no filters return all elements. Given no output schema, more context would be beneficial.
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%, giving baseline 3. The description adds no extra meaning beyond restating the optional filters; it does not explain the layer or element_type values further.
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 ('elements in the model'), and mentions optional filters. It clearly distinguishes from siblings like archimate_get_element or archimate_find_elements.
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 implies usage for listing elements with optional filters, but does not explicitly state when to use this tool vs alternatives (e.g., archimate_find_elements for text search) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List relationships, optionally filtered by element or type
| Name | Required | Description | Default |
|---|---|---|---|
| element_id | No | Filter to relationships involving this element | |
| relationship_type | No | Filter by relationship type | |
| direction | No | For element_id filter: direction of relationships |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It does not disclose that this is a read-only operation or any behavioral traits like pagination, performance, or data limits. Minimal beyond the basic purpose.
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?
One short sentence with no wasted words. Efficiently conveys purpose and filtering capability.
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 list tool with no output schema, the description is mostly adequate. It covers the basic functionality and filters. Could mention return format or read-only nature given no annotations, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The description adds no additional meaning beyond 'optionally filtered by element or type', which is already implied by the schema. Meets baseline for 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 clearly states 'List relationships' with optional filters, using a specific verb and resource. It distinguishes from sibling tools like archimate_create_relationship, archimate_delete_relationship, and archimate_list_elements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance. The description implies usage for retrieving relationships with optional filters, but does not explain scenarios or differentiate from other list tools like archimate_list_elements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all diagram views in the model
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description is minimal. It does not disclose any behavioral traits such as read-only nature or side effects beyond listing.
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?
Single sentence, front-loaded, no wasted words. Concise and to the 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?
Sufficient for a simple listing tool, but lacks details about output format, pagination, or any constraints. No output schema to compensate.
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, so schema coverage is 100%. Description adds no parameter info, but baseline is 3 per 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?
Description clearly states 'List all diagram views' with specific verb and resource. It distinguishes from siblings like archimate_list_elements and archimate_find_elements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like archimate_list_elements or archimate_create_view. No mention of context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open an ArchiMate model from a coArchi repository directory. Returns model metadata including element counts by layer.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to the model directory or model.archimate file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It states the tool 'opens' a model and 'returns metadata', but does not clarify whether it modifies files (likely read-only), whether authentication is needed, or whether the model becomes the active context for other tools. It lacks disclosure of side effects or state changes.
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, well-structured sentence that efficiently covers the action, source, and return value. Every phrase contributes meaning (action, source type, output). No unnecessary words 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?
Given the tool's simplicity (one string parameter, no output schema), the description is moderately complete. It explains what the tool does and what it returns. However, it omits details about the return format (metadata structure), the fact that the model becomes the current working model for other tools, and the requirement that the directory be a coArchi repository. These gaps reduce completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the 'path' parameter as 'Path to the model directory or model.archimate file' with 100% coverage. The tool description adds context by mentioning 'coArchi repository directory', but does not provide additional parameter constraints, examples, or formatting hints beyond what the schema offers. Hence, minimal added value.
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 action ('Open an ArchiMate model'), the source ('from a coArchi repository directory'), and the return value ('model metadata including element counts by layer'). This distinguishes it from siblings like 'archimate_create_model' (creates a new model) and 'archimate_list_elements' (lists elements within a model).
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 does not specify when to use this tool versus alternatives, nor does it mention prerequisites (e.g., that the directory must be a valid coArchi repository). There is no guidance on when not to use it or what to do after opening. For example, it does not state that subsequent operations like adding elements depend on a model being open.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save the current model to disk
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Optional path to save to (uses original path if not specified) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description is minimal, only stating 'save to disk'. Does not disclose side effects, permissions required, or behavior when no path given (though schema covers that). Lacks behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. Adequately sized for a simple operation, but could benefit from a bit more structure or context.
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 annotations and no output schema, the description is incomplete. It does not mention return value, whether it overwrites, or any locking behavior. More context is needed for safe 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?
Schema coverage is 100%, so the schema already describes the parameter. Description adds no extra meaning beyond 'save to disk', so 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?
Description clearly states action ('Save'), resource ('current model'), and destination ('to disk'). Distinguishes from sibling tools like archimate_create_model and archimate_open_model.
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?
Implies usage when user wants to persist changes, but no explicit guidance on when to use vs alternatives, prerequisites, or consequences (e.g., overwrite warnings).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing element
| Name | Required | Description | Default |
|---|---|---|---|
| element_id | Yes | ID of the element to update | |
| name | No | New name (optional) | |
| documentation | No | New documentation (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the full burden. It only states 'update' without disclosing merge vs overwrite behavior, required permissions, or what happens if element_id is invalid.
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 sentence, very concise. It could be slightly more informative without being verbose, but it is not wasteful.
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 simplicity and lack of output schema, the description does not explain return values, error handling, or side effects. This is insufficient for a mutation 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. The description adds no further meaning beyond what is already in the schema for element_id, name, and documentation.
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 updates an existing element, which is a specific verb-resource pair. However, it does not differentiate from sibling tools like archimate_create_* or archimate_delete_element.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like create or delete tools. There is no context about prerequisites or typical use cases.
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. Dates show when Glama detected each change.
v0.4.0archimate_add_connection_to_viewarchimate_add_to_viewarchimate_configure_auditarchimate_create_application_elementarchimate_create_business_elementarchimate_create_composite_elementarchimate_create_implementation_elementarchimate_create_modelarchimate_create_motivation_elementarchimate_create_relationshiparchimate_create_strategy_elementarchimate_create_technology_elementarchimate_create_viewarchimate_delete_elementarchimate_delete_relationshiparchimate_export_diagramarchimate_export_exchangearchimate_export_html_deckarchimate_export_markdownarchimate_export_mermaidarchimate_find_elementsarchimate_get_audit_logarchimate_get_elementarchimate_get_valid_relationshipsarchimate_impact_analysisarchimate_import_exchangearchimate_layer_summaryarchimate_list_elementsarchimate_list_relationshipsarchimate_list_viewsarchimate_open_modelarchimate_save_modelarchimate_update_elementEach tool has a clearly distinct purpose. The only potential overlap is between archimate_add_to_view and archimate_add_connection_to_view, but their descriptions explicitly differentiate them, with the former auto-drawing connections and the latter for manual addition.
All tools follow the 'archimate_verb_noun' pattern in snake_case, with verbs like create, delete, list, get, export, import, etc. The naming is highly consistent and predictable.
33 tools is on the higher side but still reasonable given the breadth of ArchiMate modeling (multiple layers, relationships, views, exports, audit, impact analysis). Each tool serves a specific purpose, and the count is not excessive.
The tool set covers creation, reading, updating, and deletion for most elements and relationships, as well as views, exports, imports, and analysis. Minor gaps exist: no tool to delete a view, and no update for relationships, but these are not critical.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
AI Agent with Architectural Memory. Impact analysis (free), tests and code from the graph (pro).
Public agentic AI doctrine tools plus authenticated architecture, design, and spec validators.
Architecture compiler for AI code. 11 tools, 92 actions, 872 Lean4 proofs, 100/100 self-cert.
Create and edit collaborative architecture diagrams with any AI assistant using the Trident 2D DSL.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/thijs-hakkenberg/archimate-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
