Archicad-MCP
Server Quality Checklist
Latest release: v0.1.0
- Disambiguation4/5
Most tools have clearly distinct purposes, with a few close neighbors like run_rule versus audit_delivery_readiness versus verify_ifc_export_readiness, and create_issues_from_failures versus manage_issues. Descriptions clarify the differences well, so an agent can select correctly with careful reading.
Naming Consistency4/5The dominant pattern is verb_noun (delete_elements, get_project_info, list_attributes), but there are longer descriptive names like verify_ifc_export_readiness and single-verb publish. The naming is readable and mostly predictable, though not perfectly uniform.
Tool Count3/525 tools is on the heavy side, but the breadth of Archicad functionality (model elements, QA rules, issues, schedules, publishing, API introspection) justifies many of them. A few tools could be merged or exposed through the generic execute_api_command, but the count is still within a defensible range.
Completeness4/5The surface covers element CRUD, queries, property reading/writing, selection, attributes, QA rules, issues, scheduling, publishing, and a generic API fallback. Minor gaps exist—such as no dedicated element update tool and schedule criteria editing being unavailable—but the generic execute_api_command plus schedule tools mitigate most dead ends.
Average 3.6/5 across 24 of 25 tools scored. Lowest: 2.6/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 95 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add
glama.jsonto the root of your repository:{ "$schema": "https://glama.ai/mcp/schemas/server.json", "maintainers": [ "your-github-username" ] }Then . Browse examples.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not mention any side effects, destructive potential, or irreversible actions. Since actions like 'create' and 'delete' (implied by 'manage') may have significant consequences, the lack of warning is a transparency gap. No annotations compensate for this omission.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, listing actions in a clear format (action = list | create | ...). It avoids unnecessary words, making it easy to parse, though it could benefit from a brief explanation of each action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no parameter descriptions, the tool is incomplete. The description does not clarify expected inputs for each action, return values, or error conditions, making it insufficient for reliable execution without external documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no information about the seven parameters (name, port, guids, action, comment, bcf_path, issue_id). The schema lists types but no explanation of their purpose or relationships, leaving the agent to guess how to fill them for each action.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as managing Archicad issues and enumerates the possible actions (list, create, comment, attach, export, import). This distinguishes it from other tools like delete_elements or get_project_info, though it doesn't elaborate on each action's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool compared to alternatives. It does not indicate scenarios where issue management is appropriate or how it relates to other operations, leaving the agent without situational context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for disclosing behavioral traits. It only states the action and fails to mention potential side effects (e.g., generating output files), whether the operation is blocking, permission requirements, or reversibility. This lack of transparency is a notable gap for a mutation-like tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no waste. It efficiently conveys the core action and resource. However, it is borderline under-specified, but conciseness itself is good.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this tool has two parameters, no annotations, and an output schema, the description is too minimal to be contextually complete. It lacks guidance on when to use, parameter semantics for 'port', and any note on side effects. The existence of an output schema partially compensates for return format understanding, but not enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must explain parameters. It only implies publisher_set_name by saying 'by name', but offers no explanation for the optional 'port' parameter. Without additional context, an agent cannot determine the purpose or acceptable values for 'port'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's action ('Fire' = trigger) and resource ('Archicad publisher set by name'), making it distinguishable from sibling tools, none of which overlap with this specific publishing functionality. While 'Fire' is slightly informal, the resource and context make the purpose reasonably clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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, no prerequisites, and no exclusions. It simply states the action without contextualizing its role in a workflow or comparing it to other tools like execute_api_command or run_rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. However, the description is minimal—it doesn't disclose behavior beyond the fact that it lists attribute names by type. No mention of authentication, rate limits, side effects (it is read-only presumably), or what happens on invalid input. The description is too sparse to provide meaningful transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that gets straight to the point without any fluff. It packs the core information (list attribute names, the type parameter, and valid values) into a compact format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 parameters, no nested objects) and the presence of an output schema, the description is mostly sufficient for a basic list operation. However, it could have added value by clarifying the 'port' parameter's role or mentioning if the list is sorted or limited, which would make it more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description only hints at the 'attribute_type' parameter by listing valid types. There is no mention of the 'port' parameter at all, and the description does not add meaning beyond what the raw schema shows. Since the description does not compensate for the schema's lack of documentation, this scores low.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb (list) and resource (attribute names) with a specific type parameter (Layer, BuildingMaterial, Composite, Surface, Profile, ZoneCategory). This effectively differentiates it from siblings like list_instances or list_rules, though it doesn't explicitly name a sibling for comparison.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by indicating that the type parameter is required and lists valid types, which tells the agent when to use this tool (to list attributes by type). However, it does not explicitly state when NOT to use it or name alternatives from the sibling tools, so it's adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses the return verdict components (pass/fail, count, GUIDs) and implies a validation action, but it does not specify if running the rule is read-only or if it mutates data, triggers background processes, or requires specific permissions. It adds some behavioral detail but not enough for a full safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, two sentences, and front-loaded with the purpose. It provides essential output info without extra fluff. It could be slightly more structured, but it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return details are presumably structured, but the description does not explain the 'port' parameter or the execution context (e.g., whether it runs on the current project). It is incomplete for a two-parameter tool with zero coverage, but the output description adds value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description says nothing about the 'port' parameter, which has no clear semantics in the schema. The rule_id is obvious, but port is unexplained. Description does not compensate for the undocumented parameter, though it does clarify the return value meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs a QA rule by ID and returns a verdict with pass/fail, failure count, and failing element GUIDs. It is specific with a verb+resource, and distinct from siblings like list_rules or query_elements. It could mention the side-effect nature (running a rule may trigger validation), but the core purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like list_rules or get_model_summary. It does not state prerequisites, such as needing a valid rule_id, or whether running a rule has side effects. The description is task-focused but lacks contextual usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It reveals the Tapir add-on requirement and that failing elements are attached, but it does not mention side effects, permissions, reversibility, or how existing issues are handled—significant gaps for a 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that includes the core action, source, output, and a key dependency. There is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema likely covers return values, but the rest of the context is thin: no parameter mapping, no usage workflow (e.g., run_rule first), no side-effect or failure-mode information. For a tool with two parameters and no annotations, this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning for either parameter. It never explains that rule_id identifies the rule whose failures are used, nor what port represents, leaving the agent without semantic guidance for required or optional inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create an Archicad issue), the source data (a rule's failures), and what gets attached (the failing elements). It also differentiates from siblings like run_rule and highlight_failures by specifying the issue-creation outcome.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite (requires Tapir add-on) and implies this tool is used after a rule has produced failures, but it does not explicitly explain when to choose this over related tools like run_rule or highlight_failures, nor does it state exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does not mention any side effects, such as whether setting a selection requires prior element references, whether it modifies the project state permanently, or if there are any constraints (e.g., only works on certain element types). The description only lists the actions without explaining consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, a single sentence, and front-loads the core purpose. It wastes no words, but it omits critical detail about the other parameters and behavioral context, which might be a case of over-conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters, no annotations, and an output schema, but the description does not compensate for the missing param semantics or behavioral context. It lacks information about return values (though output schema exists, it could be complex) and fails to explain the 'port' and 'guids' parameters. Given the tool's moderate complexity, this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must clarify parameters. It mentions 'action' with allowed values but does not explain 'guids' (likely a list of GUIDs) or 'port' (likely an API port). The description adds minimal value by naming 'action', but fails to explain the other parameters' semantics, which is essential given the 0% coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to get, set, or clear the current element selection in Archicad. It specifies the verb and resource, and the 'action' parameter distinguishes the three modes. However, it doesn't explicitly differentiate from siblings like 'query_elements' or 'set_element_data' beyond the selection scope, which is somewhat implied.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates the tool is used to manage the current selection, which implies it should be used when the agent needs to manipulate or retrieve the selected elements. However, it provides no explicit guidance on when to use this instead of alternatives like 'query_elements' or 'set_element_data', nor does it mention prerequisites or context such as requiring an open project.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It states the tool returns project info and mentions 'Tapir enriches', which seems to indicate some added functionality or dependency. However, it does not disclose potential side effects, required permissions, or limitations. The mention of 'geolocation presence (Tapir enriches)' is vague and could confuse agents.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, a single sentence that lists key contents. It is front-loaded with the purpose. However, the parenthetical 'Tapir enriches' adds ambiguity and could be removed or clarified, but overall it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (which is not shown here), the description may not need to detail return values. However, it does not mention the port parameter or any usage notes. The tool seems relatively simple (no required params), but the lack of parameter explanation and the vague 'Tapir enriches' leaves room for improvement. It is borderline adequate for a simple info query.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the only parameter 'port' is not explained in the description. The description does not mention the port parameter at all, leaving the agent unsure why it is needed or how to set it. With 0% coverage and only one parameter, the description should have explained its role, but it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: retrieving project information such as Archicad version, project name, stories, hotlinks, and geolocation presence. It uses specific nouns related to the domain. However, it does not explicitly contrast with siblings like get_model_summary, which might cover similar ground, so it lacks some differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a read-only informational query, but it does not provide explicit when-to-use guidance or alternatives. Given the context of sibling tools, it is likely used for project-level metadata, but the description does not articulate when to choose this over get_model_summary or other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions a dependency (Tapir add-on) but does not specify whether the tool is read-only, what happens if the add-on is missing, or what output it produces. This is a significant gap for a QA tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and a key requirement. Every word earns its place with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description lacks critical context: the 'port' parameter is unexplained, and there is no mention of failure conditions, side effects, or what specifically constitutes 'IFC export readiness'. The tool's simplicity is mitigated by the parameter gap and missing behavioral details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter ('port') with no description, and schema coverage is 0%. The description does not mention the parameter at all, leaving the agent without any guidance on what 'port' means or how to use it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Run only the IFC-related QA rules to check IFC export readiness.' It uses a specific verb ('run') and identifies a distinct resource/scope (IFC-related QA rules) with a clear purpose. This differentiates it from sibling tools like 'run_rule' and 'audit_delivery_readiness'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage context by specifying 'only the IFC-related QA rules' and notes a prerequisite ('Requires the Tapir add-on for IFC data'). This implies when to use the tool (when IFC export readiness is needed) and gives a condition, but it does not explicitly mention alternative tools 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that it runs all QA rules optionally filtered by ruleset and returns a scored verdict, indicating a read-only audit. However, it omits performance implications, error behaviors, or what 'loaded' means operationally.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences accomplish the goal without waste. It front-loads the action and return value, using parenthetical detail for the optional filter—highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The presence of an output schema reduces the need to describe return values, and the description covers the core function. However, the unclear 'port' parameter and the meaning of 'loaded' rules create gaps that a bit more context could fill.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain both parameters. It addresses 'ruleset' by mentioning filtering by that tag, but 'port' is completely unexplained. This leaves half the parameters underspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Run') and resource ('all loaded QA rules') against 'the open model', returning a 'scored verdict'. It differentiates from sibling 'run_rule' (singular) by indicating a batch operation, and the optional 'ruleset' filter clarifies scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use guidance or exclusions are provided. The description implies batch auditing but does not contrast with alternatives like 'run_rule' or 'verify_ifc_export_readiness', nor does it mention prerequisites such as rules being 'loaded'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It explicitly discloses the most critical traits: the operation is IRREVERSIBLE and refuses to execute without confirm=true. It could add more detail about partial failures, permissions, or side effects, but the core destructive behavior is clearly surfaced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, front-loaded, and every word serves a purpose: the action, the irreversible nature, and the confirmation gate. There is no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides essential safety context and an output schema exists, so return values do not need explanation. However, it lacks any usage context, alternative guidance, or semantics for the port parameter, making it minimally viable but incomplete for a destructive tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning for the confirm parameter by stating the tool refuses without confirm=true, but it does not explain guids or the port parameter, leaving most parameter semantics unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource combination, 'Delete elements,' which clearly identifies the tool's action and distinguishes it from siblings like create_elements, move_elements, or query_elements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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, or when not to use it. The confirmation requirement is mentioned, but there is no contextual guidance, prerequisites, or exclusions beyond that.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden, but it only states what data is returned ('full description and input schema'), without addressing side effects, errors, or security considerations. The phrase 'Call before execute_api_command' implies a safe preflight check, but it does not explicitly declare the operation as read-only because the agent is expected to infer that from the name. It's 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the tool's purpose and a clear call-to-action. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single-parameter input and the presence of an output schema that presumably documents the return structure, the description sufficiently enables an agent to understand the tool's role. Could be enhanced with a note on the source of the command name, but overall it's adequate for a low-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no information about the single required parameter, `name`. Since coverage is low, the description should compensate by explaining where `name` comes from (e.g., a command name from list_api_commands) or its format. This is a significant gap for an agent preparing to invoke the tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's function—retrieving the full description and input schema for a single API command. However, it uses a noun phrase rather than a strong verb, and while 'Call before execute_api_command' hints at a workflow, it does not explicitly contrast with sibling tools like list_api_commands. Overall, purpose is clear but not outstanding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The instruction 'Call before execute_api_command' provides an explicit usage guideline with a clear temporal context. However, it lacks explicit exclusions or alternative mentions, such as when not to use this tool or how it compares to enumeration tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the Tapir add-on dependency but does not mention whether the operation is read-only, clears previous highlights, or what happens if the rule fails or has no failures.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no wasted words. It immediately states the action, target, and a key prerequisite.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema covers return values, and the tool is simple. However, the lack of parameter descriptions and minimal behavioral transparency leave gaps, though not severe enough for a lower score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not explicitly explain the parameters. 'failing a rule' hints at rule_id but does not describe its format or purpose, and port is entirely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states a specific action ('Highlight') on a specific resource ('the elements failing a rule') with a location ('in the Archicad window'). This distinguishes it from siblings like run_rule or create_issues_from_failures.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context by stating it requires the Tapir add-on, implying use when that add-on is available. However, it does not explicitly contrast with alternatives or give when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that it lists 'loaded' rules and includes error reporting ('rule-file load errors'), which adds behavioral context beyond a simple list. However, it does not detail output format or behavior when no rules are loaded.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loads the main action, and includes parenthetical detail on returned fields. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter tool with a simple purpose and an output schema, the description is complete. It covers what the tool lists and mentions error reporting. It could specify return format if absent from output schema, but this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and 100% schema coverage (empty object), the baseline is 4. The description adds context about what the output contains (id, type, severity, tags) and error reporting, which enriches the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb ('List') and resource ('loaded QA rules'), specifies the output fields (id, type, severity, tags), and mentions load errors. It doesn't explicitly differentiate from siblings, but the resource (QA rules) is distinct enough among the sibling names.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage via 'List loaded QA rules' and mentions 'and any rule-file load errors,' giving context on when to use it (e.g., to inspect QA rules or errors). No explicit exclusions or alternatives are mentioned, but the purpose is clear enough for a simple list operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden, but it only discloses that params are validated against a bundled schema where available. It does not warn about potential side effects, error behavior, permission requirements, or the destructive/arbitrary nature of executing any API command.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, front-loaded with the core action and target. Every sentence adds useful information: what it executes, validation behavior, and preference for dedicated alternatives.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an arbitrary command executor, the description gives the essential fallback role and validation note, and an output schema exists to describe returns. However, it lacks guidance on how to discover valid commands or param structures, and fails to flag risk or side effects for a tool that can execute any API command.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate, but it only tells the agent commands are executed 'by name' and that params are validated. It does not explain the semantics of the 'port' parameter, the flexible 'params' input, or expected parameter shapes/formats.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Execute' and the resource 'any Archicad API command', including the specific command kinds ('API.*' or Tapir). This distinguishes it from dedicated sibling tools by framing it as a general-purpose executor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The final sentence explicitly says to prefer dedicated tools when one exists, providing clear when-not-to-use guidance. It also implies this is the fallback for arbitrary commands, which is reinforced by the sibling tool list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With zero annotations provided, the description carries the full burden, and it delivers three critical behavioral facts: (1) the operation is a relative displacement (by a vector), not an absolute move-to-position; (2) the vector is interpreted in meters — a unit convention that could silently cause massive scaling errors if wrong; and (3) the tool refuses to execute without `confirm=true`, explicitly gating a mutating operation on explicit user confirmation. It does not disclose side effects, reversibility, or what happens on refusal (error vs. silent no-op), which prevents a 5. But for a 16-word description, this is substantial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, 16 words, and every single one earns its place. The first sentence front-loads the action ('Move elements') and the displacement details (vector, units), while the second delivers the most operationally critical constraint (confirmation required). There is zero redundancy, no filler, and the structure leads with the most important information. This is a model of concision.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating operation with 4 parameters (2 required), no annotations, no schema-level descriptions, and a `port` parameter that is completely opaque, this description leaves significant gaps. The most glaring omission is `port` — an AI agent has no way to know if it's needed, what values are valid, or what the default `null` means. The `guids` parameter is assumed self-evident but not confirmed in context, and the behavior on missing/invalid GUIDs is unknown. The presence of an output schema helps with return values but doesn't compensate for the incomplete input contract. The `confirm` gate is also unexplained — does the agent need to set it to true always, or only for bulk operations?
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description meaningfully enhances the `vector` parameter by giving it structure ({x,y,z}) and units (meters), which is not in the schema at all. It also implicitly documents the `confirm` parameter's purpose (safety gate to prevent accidental moves). However, it completely ignores `guids` (which array elements? element IDs? names?) and `port`, which is highly ambiguous — it could be a network port for an API connection, a design viewport, or something else entirely. Given that this is 0% schema coverage, the description only partially compensates for the gaps, leaving a critical parameter undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
"Move elements by a vector {x,y,z} in meters" is a precise verb+resource specification that clearly outpaces any sibling tool. The description differentiates from siblings like delete_elements, create_elements, query_elements, and get_element_data by specifying both the relative nature of the move (by a vector) and the exact structure of that vector ({x,y,z} in meters). This is exactly the kind of clarity that eliminates ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool's purpose (move elements relative to their position) but never explicitly states when to use it versus alternatives. The mention of `confirm=true` hints at a workflow (you must pass this to proceed) but doesn't name sibling tools like `manage_selection` or `query_elements` that might be used together or instead. No exclusions or caveats about element types, permissions, or interactivity with selections are given. This is implied usage only, which meets the 'adequate but with clear gaps' bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the dry-run default and that dry_run=false triggers actual creation, which is important. However, it does not mention potential side effects, permissions required, or error handling, leaving some behavioral aspects opaque. Since there are no annotations, this is a moderate level of transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, using all-caps for emphasis on the dry-run behavior and clearly separating the main purpose from usage notes. Every sentence contributes meaning without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core functionality, usage guidance, and distinguishes from a sibling tool, which is sufficient for most context. It does not delve into return values, but given that an output schema exists (as indicated in context), this is not required. It could be more detailed on edge cases, but overall it is complete enough for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains element_type (by listing valid types) and dry_run (by describing its effect). It does not clarify the semantics of items (presumably the list of elements to create) or port. With 4 parameters, only half are explained, so the description adds moderate value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool creates elements of specific types (column/slab/zone/polyline/object/mesh) via Tapir, and distinguishes itself from execute_api_command for other types. It also notes the dry-run default behavior, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool (for listed element types) and when to use execute_api_command for other types. It also explains the dry-run default and how to override it with dry_run=false, giving clear usage instructions. While not exhaustive, it covers the key decision points.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It states 'Read' which implies a non-destructive operation, but it does not explicitly declare read-only status, error handling for missing GUIDs, or any potential side effects. It adds some useful context (property addressing syntax, optional classifications) but lacks explicit safety or failure behavior. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is a single, front-loaded sentence. It packs the core purpose, key usage detail (property address format), and optional behavior (classifications) with zero redundancy or filler. Every word contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters and an output schema, so the description does not need to detail return structure. It covers the primary purpose, clarifies property syntax, and notes optionality. However, it omits any mention of the 'port' parameter and does not address edge cases like empty GUID lists or invalid GUIDs. For a read-oriented tool with a modest parameter count, it is mostly complete but has a few gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does explain the 'properties' parameter by specifying the addressing format ('Group/Name') and clarifies that 'include_classifications' is optional. However, it says nothing about the 'port' parameter, which remains ambiguous. Since two of the three non-obvious parameters are at least partially explained, it earns a middle score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Read') and resource ('element data') with clear scope: 'given element GUIDs'. It explicitly mentions the types of data returned (type, layer, properties, classifications) and includes a critical usage detail (address user properties as 'Group/Name'). This distinguishes it from sibling tools like delete_elements or get_project_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates when to use this tool: when you have element GUIDs and need to read their data. It implies that this is the direct-by-GUID accessor, contrasting with filtering tools like query_elements or list_instances, though it does not explicitly name alternatives or state when not to use it. The context is clear enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. 'Catalog of ALL available commands' and the verb 'list' clearly imply a read-only, non-mutating operation. It also adds useful scope context (official JSON API + Tapir) and the optional group filter behavior, though it does not discuss output volume or ordering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence and front-loads the core purpose. Every word adds value, and there is no redundant metadata or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, with one optional parameter and an output schema present, so the description does not need to explain return values. The description covers what the tool does, what it includes, and how it can be narrowed, which is sufficient for safe selection. It could mention how groups are structured, but the overall context is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must clarify the parameter. It states that 'group' filters the catalog, which adds meaning beyond the schema's raw field name. However, it does not explain what group values are valid, how to discover them, or the exact format/usage of the filter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb pattern ('Catalog...') with a clear resource: ALL available Archicad API commands across both official JSON API and Tapir. It also distinguishes itself from sibling tools like describe_api_command and execute_api_command by being a catalog/list operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is meant for discovering/browsing available commands, and the optional group filter gives a sense of when it might be narrowed. However, it does not explicitly state when to use this tool versus describe_api_command or execute_api_command, nor does it mention any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It transparently explains the dry-run behavior, that it returns planned changes without touching the model, and that committing requires dry_run=false. This sufficiently discloses the side effects and return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief—two sentences—and contains no redundant information. It is well-structured and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main behavior (dry-run vs commit) and return value, but it omits details about the parameters, especially the expected format of 'changes'. While the tool name and context give some hint, the lack of parameter explanation leaves it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema parameters (port, changes, dry_run) are not described in the tool description. The 'changes' parameter is central but its structure is not explained, and 'port' is ambiguous. The description adds no parameter-level detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Write element property values', which is a specific verb and resource. It clearly distinguishes from sibling tools like delete_elements and create_elements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies this is for modifying element properties, and the dry-run default is a key usage note. However, it does not explicitly state when to prefer this over alternatives, though the context is fairly clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: it is dry-run by default, never overwrites the input, writes to a specific location, and clarifies that the need for an Archicad connection depends on how properties are bound (GUID vs Group/Name). This is highly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed but not excessively verbose. It is logically structured, covering the main action, default behavior, output location, import instruction, and dependency on a live connection. Each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides a solid overview of the tool's functionality, including key constraints and prerequisites. It lacks explicit explanations for all parameters but covers the core use case and edge conditions well enough for an agent to use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the roles of 'path' and 'spec_path' indirectly, and mentions 'output' and 'dry_run' in behavior, but does not clarify 'port' or 'spec_id'. Since the schema provides no descriptions, the coverage is partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: applying a YAML scheme spec to an exported schedule scheme XML, with specific actions like setting columns, retargeting bindings, and renaming. It distinguishes this editing operation from other tools in the sibling set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the default behavior (dry-run) and output file naming, but does not explicitly state when to use this tool versus alternatives or provide contextual usage conditions. The user must infer that this is for editing schedule schemes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It explicitly states that include_layer_story is 'refused on very large models (can crash Archicad)', discloses that it 'reads a property across every element', and explains the meaning of 'coverage' (whole-plan vs. model-elements-only). It also notes that by_type is 'cheap and safe' and that the tool returns counts only, never element data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph but front-loaded with the main purpose. Each sentence contributes useful information (e.g., safety, warnings, coverage semantics), and there is no fluff. However, the paragraph is dense and could be split into cleaner sections for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 2 parameters and an output schema. The description covers the essential behavioral aspects (what the tool returns, the meaning of 'coverage', the safety implications of include_layer_story). The missing port explanation is the main gap. Since an output schema exists, return values are handled separately, but the port parameter remains unexplained, reducing completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero description coverage (0%), so the description must explain all parameters. It explains include_layer_story thoroughly (what it does, when to set it, and its risks), but completely ignores the 'port' parameter. Since port is part of the schema and lacks any description, the semantics for that parameter are missing, leaving a critical gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool aggregates element counts, differentiating it from sibling tools like query_elements (which return data) and get_element_data. It specifies the verb (aggregate) and resource (element counts), and the distinction from other tools is evident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by stating 'Counts only, never element data,' indicating when not to use it (if you need element data). It also clarifies the coverage semantics (whole-plan vs. model-elements-only) and warns about include_layer_story on large models. However, it doesn't explicitly name alternative tools, so it misses a direct 'use instead of X' statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the transparency burden. It discloses the AND-combination behaviorched returns GUIDs and counts, and importantly notes the coverage difference with/without the Tapir add-on, including the caveat that zero counts aren't proof of absence. This is useful behavioral insight beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that pack essential information: what the tool does, its filters, return values, and a critical caveat about coverage. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a query tool with 6 optional parameters and an output schema, the description covers the essential behavior: AND-combination of filters, return type (GUIDs and counts), and the important coverage caveat. It doesn't explain each parameter's semantics or error cases, but given the self-explanatory names and existing output schema, it's adequately complete for an agent to select and use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has no parameter descriptions (0% coverage), so the description compensates by listing the filter names and explicitly stating they are AND-combined. It also clarifies the selection_only parameter's role. However, it doesn't elaborate on the meaning of each parameter (e.g., layer vs. story), though the names are self-explanatory. Overall, it adds meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queries elements with specific AND-combined filters (element_type, layer, story, classification_system, selection_only) and returns GUIDs and counts. It also mentions the 'coverage' field, which distinguishes it from sibling tools that manipulate or get data for specific elements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need to query elements with filtersaine, and the coverage caveat provides context for interpreting results. However, it does not explicitly mention when not to use it or name alternative tools, relying on the user to infer from the tool list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explicitly discloses that the tool reads property definitions only, not values, and thus avoids the property-read crash. This is a critical behavioral safety detail that goes beyond the schema. However, it does not describe other behaviors like error handling or idempotency, so a 4 is fair—it adds significant context but is 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose. The second sentence adds a crucial safety disclaimer. No fluff, every word earns its place. This is exemplary conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a moderate complexity: it checks bindings and captions, with a safety caveat. The output schema exists (likely a report of issues), so the description doesn't need to explain return values. The description covers the what and the safety aspect, but misses explaining the port parameter and any prerequisites. Given the output schema and the clear purpose, a 4 is appropriate; it is complete enough for most cases but leaves the port parameter undocumented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has two parameters: path (required string) and port (optional integer/null). Schema description coverage is 0%, so the description must compensate, but it does not mention the parameters at all. The description implies the path is the scheme file, but does not explain the port parameter. Baseline for low coverage and no param info is low; I assign a 3 because the description adds some context about the tool's purpose (validating an exported scheme) which hints at the path parameter, but port remains unexplained. With 2 parameters and 0% coverage, a score of 2 would be justified, but considering the description gives overall purpose that disambiguates parameters, I give 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool validates an exported schedule scheme against the open project, checking for missing property bindings and column caption mismatches. It specifies the resource (schedule scheme) and the action (check/validate), distinguishing it from siblings like read_schedule_scheme and edit_schedule_scheme.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: use this to validate an exported scheme before applying it, or to detect inconsistencies. It does not explicitly state when not to use it or name alternatives, but the mention of 'check against the open project' gives clear context. A score of 4 is appropriate because it provides context without explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. The verb 'List' and the listed output fields imply a read-only discovery operation, but the description does not explicitly state no side effects, permissions needed, or behavior when no instances are running. It is adequate but not richly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every phrase contributes: the action, the target, the output fields, and the call-order guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters and an output schema present, the description is complete for a low-complexity discovery tool. It covers what the tool lists and explicitly frames it as the first call in the workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and 100% schema description coverage, so the baseline is 4. The description needs no parameter-level detail because there are no parameters to document.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a clear resource ('running Archicad instances') and enumerates the returned fields (port, version, open project, Tapir add-on availability). This clearly distinguishes it from sibling tools like get_project_info or get_model_summary, which focus on project/model data rather than instance discovery.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Call this first' provides explicit when-to-use guidance, positioning the tool as the entry point for the suite. It doesn't name alternatives or exclusions, but for a parameterless discovery tool this is sufficient context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description clearly states it 'Reads the file only, never Archicad', making it non-destructive and isolated. It also mentions it doesn't connect to Archicad, which is important context. It doesn't mention error handling, but for a simple read operation this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded. The first sentence states the purpose, the second gives usage instruction and behavioral note. No wasted words, ideal length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given it has an output schema separately, the description sufficiently covers the input and behavior. It explains the source of the file河南int and the read-only nature. It's complete for a single-parameter read tool, though it could mention that it expects a valid XML file format, but that's implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'path' is described as the file path to the exported XML. The description says 'pass the file path', and context about exporting from Archicad clarifies its meaning. With 0% schema description coverage, this explanation is necessary and sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to describe an exported Archicad schedule scheme XML, including criteria and column bindings. This is specific and distinguishes it from sibling tools like edit_schedule_scheme and validate_schedule_scheme, which imply modification and validation respectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains the prerequisite (export the scheme first) and why it's needed (no API), which guides when to use this tool. It also implicitly differentiates from editing or validating by focusing on reading/describing, though it does not explicitly mention exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/alesdev88/Archicad-MCP'
If you have feedback or need assistance with the MCP directory API, please join our Discord server