Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false and destructiveHint=true, and the description aligns with a write operation. It adds the useful Tapir add-on dependency, but it does not describe any side effects or the permanent nature of the comment, which is relevant given the destructive hint.

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 action and target, followed by the add-on prerequisite in parentheses. There is no redundant wording.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-required-parameter mutation with an output schema available, the description plus annotations cover the core usage and dependency adequately. The only notable omission is the port parameter, which is minor since it is optional and defaults to null.

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 0%, so the description must explain the parameters. It does so for issue_id ('addressed by its id') and comment ('text comment'), but the optional port parameter remains entirely unexplained, leaving a gap.

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 ('Add') and resource ('text comment to an existing issue'), and clearly identifies that the target is addressed by its id. This distinguishes it from siblings like create_issue or attach_elements_to_issue.

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 states the prerequisite that the Tapir add-on must be installed and implies the issue must already exist, but it does not name alternatives or explicitly explain when not to use this tool. The intended use case is clear but exclusion guidance is missing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate a mutating and destructive operation, so the description does not need to restate that. It adds useful context: the element must be an existing issue and the Tapir add-on is required. It does not explain what destruction may occur, but it does not contradict the annotations either.

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 one compact sentence that front-loads the core action, target, and result type, then adds the important prerequisite. There is no repetition, filler, or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With annotations and an output schema present, some context is already supplied. The description covers the core action and the add-on requirement, but leaves gaps around optional parameters, the exact meaning of 'highlights', and how this differs from sibling issue-attachment workflows. It is adequate but not 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?

Schema description coverage is 0%, so the description must compensate. It only loosely maps 'elements' to guids and 'issue' to issue_id, but it says nothing about the 'port' parameter, the format of guids, or the relationship between them. An agent would still have to guess the full 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 uses a specific verb ('Attach') with a clear resource ('elements') and an explicit target ('an existing issue') and adds the qualifier 'as highlights'. This meaningfully distinguishes it from siblings like move_elements, delete_elements, and add_issue_comment.

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 the tool is for attaching element references to an issue as highlights and notes the Tapir add-on prerequisite. However, it gives no explicit guidance about when not to use it or how it compares to related tools such as add_issue_comment or create_issues_from_failures.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful context about scope ('all loaded QA rules') and the optional ruleset filter, but does not disclose potential runtime costs, connectivity requirements, or behavior when no rules are loaded. Still, it does not contradict 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?

One compact sentence delivers the core action, the optional filter, the target, and the result. No filler or redundant restatement of the tool name/title.

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 output schema exists, so not describing the exact return structure is acceptable. However, the 'port' parameter is entirely unexplained, and the description assumes an 'open model' without clarifying prerequisites or failure modes. This is adequate for a simple read-only tool but has a clear semantic 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 0%, so the description must compensate. It explains the 'ruleset' parameter as an optional tag filter, but completely omits the 'port' parameter, leaving its meaning and effect unclear. Given two parameters and no schema descriptions, this is a notable gap.

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 ('Run') and names the exact resource ('all loaded QA rules') against the 'open model', with an explicit optional filter. It also states the return type ('scored verdict'), making its purpose distinct from siblings like run_rule or verify_ifc_export_readiness.

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 when to use it: when a full or ruleset-filtered QA audit is needed against the open model. However, it does not explicitly contrast with run_rule or other QA-related siblings, nor does it state conditions where an alternative would be preferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=false and destructiveHint=false, and the description does not contradict them. It adds the scope of the action ('in the Archicad window') but does not mention side effects, prerequisites, or whether the selection change affects model data. No annotation contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no redundant words. It earns its place as a concise, direct statement of the tool's function.

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 definition is minimally viable for a simple command, and the output schema plus annotations cover some context. However, it lacks explicit usage guidance and any parameter semantics, which prevents it from being fully self-contained.

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 has one parameter ('port') with 0% description coverage, and the tool description does not explain it. Since the parameter is optional with a default, the gap is minor, but the description does not compensate for the missing schema 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 uses a specific verb ('Deselect') and a clear resource ('everything in the Archicad window'), making the operation unambiguous. It is immediately distinguishable from siblings like get_selection and set_selection.

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 given about when to use this tool versus alternatives such as set_selection with an empty list, or how it relates to get_selection. The description states only the action, leaving usage to be inferred from the tool name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate this is a non-readonly, destructive-capable write operation. The description adds important behavioral context beyond the annotations: the dry-run default, that it prints the exact command and payload, and that dry_run=false is required to perform the creation. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences with no filler: purpose first, the critical dry-run behavior second, and alternate routing last. Every sentence earns its place.

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, combined with annotations and an output schema, covers tool selection, safety behavior, and how to trigger real execution. The main gap is the lack of detail on the 'items' payload structure and 'port' semantics, but the dry-run default lets an agent safely discover the expected format.

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 0%, so the description carries the burden for parameter meaning. It usefully explains dry_run's default and gives example values for element_type, but it does not explain the required 'items' array or the optional 'port' parameter. This is partial compensation only.

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') and resource ('elements'), enumerates supported element types, and explicitly separates this tool from execute_write_api_command for 'other types'. This lets an agent distinguish it from the generic write command without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says the tool is dry-run by default, explains how to actually create with dry_run=false, and directs unsupported command types to execute_write_api_command. This is direct when-to-use and when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already convey the mutation/destructiveness profile, and the description adds the useful Tapir add-on requirement. It also discloses that the operation returns an id; however, it does not explain any side effects beyond creation, which is acceptable because destructiveHint is already present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence conveys the core action, scope, return behavior, and a dependency without repetition or filler. It earns its place efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Although the output schema likely covers the returned id and annotations cover the safety profile, the description is not complete enough for reliable invocation: the port parameter is undocumented and there is no guidance for choosing this tool over related issue-creation or issue-comment 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 description coverage is 0%, so the description must compensate. The name parameter is weakly inferable as the issue's name, but the optional port parameter is completely unexplained, leaving its role and accepted values ambiguous.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action and resource: create a new issue in the open project, and it names the immediate result (return its id). This is distinct from siblings like add_issue_comment or create_issues_from_failures, which have clearly different scopes.

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 primary usage is implied: use this tool when a new issue should be created in the open project. The mention of the Tapir add-on acts as a prerequsite, but there is no explicit comparison to alternatives such as create_issues_from_failures or import_issues_bcf.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=false and destructiveHint=true, so the write/destructive nature is declared. The description adds useful behavioral detail about attaching failing elements and the Tapir dependency, but it does not reveal what destructive effects may occur or what gets modified beyond the new issue.

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, tight sentence that front-loads the core action and source, then adds the prerequisite. Every word earns its place, with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity, the presence of annotations, and an output schema, the description is mostly adequate. However, the unexplained port parameter and lack of explicit sibling differentiation leave meaningful gaps for an agent trying to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It indirectly references rule_id through 'rule's failures,' but it says nothing about the port parameter at all, leaving one of two parameters entirely undocumented.

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 a specific action ('Create an Archicad issue'), the source data ('from a rule's failures'), and an additional behavior ('attach the failing elements'). This is sufficient to distinguish it from the generic sibling create_issue and from other issue-related 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 when to use this tool, namely when there are rule failures to convert into issues, and it provides a prerequisite ('requires Tapir add-on'). However, it does not explicitly route agents away from alternatives such as create_issue or explain 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, but the description adds meaningful behavioral context beyond that: deletion is irreversible and the tool refuses to act without confirm=true. This informs the agent of the safety gate and irreversible side effects, which are not visible in the schema or annotations. The added value is substantial for a 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 composed of three short, purposeful fragments: the action, the irreversibility warning, and the confirm requirement. Each sentence earns its place and the critical caution is front-loaded. There is no redundant phrasing or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive tool with three parameters, zero schema coverage, and no parameter descriptions, the description is far too sparse. It omits the meaning of guids, the role of port, what 'elements' refers to, and the operational scope of deletion. An output schema exists but does not clarify invocation semantics. The description works as a warning label but not as complete tool documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for three undocumented parameters. It only clarifies confirm (it must be true) and says nothing about the required 'guids' or optional 'port.' The most important parameter, guids, is completely unexplained, leaving the agent to infer what identifiers are expected. Partial compensation is insufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Delete elements') and immediately adds the key qualifier 'IRREVERSIBLE,' making the operation unambiguous. No sibling tool performs deletion, so there is no risk of confusion with move/create/query tools. The purpose is clearly distinguished from all alternatives.

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 choose this tool versus alternatives such as move_elements or create_elements. The only instruction, 'Refuses without confirm=true,' is an invocation precondition rather than a decision rule for tool selection. An agent receives no context about appropriate use cases or conditions that should prevent deletion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the tool returns a full description and input schema and should be called before execution, but it does not disclose additional behavioral details such as whether the command name must come from a fixed list or what happens if an invalid name is provided.

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 short sentences with no filler. The purpose is stated first, and the crucial usage instruction follows immediately, making it easy for an agent to parse and act on.

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 one-parameter, read-only tool with an output schema, the description covers the essential purpose and usage. The only notable gap is not pointing to list_api_commands as the source for valid command names, but this is a minor omission given the sibling context.

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 only defines 'name' as a string with no description, and schema coverage is 0%, so the description must compensate. The phrase 'for one API command' implies that 'name' identifies a specific API command, but it does not explain where to find valid command names or that list_api_commands can be used for that purpose.

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 function: retrieving the full description and input schema for a single API command. It also distinguishes itself from the execution tools by explicitly saying to call it before execute_read_api_command or execute_write_api_command.

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 gives explicit guidance to call this tool before the execute commands, which clearly establishes its role as a prerequisite/introspection step. It does not explicitly mention list_api_commands as an alternative for discovering command names, so it falls slightly short of a full when-to-use vs when-not-to-use explanation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only say readOnlyHint=false and destructiveHint=true. The description adds crucial behavior: dry-run by default, writes nothing until dry_run=false, never overwrites input, writes to output or <name>.edited.xml, criteria are preserved but not editable. It also discloses the output (before/after column lists) and offline/online requirements. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but efficient: each sentence adds a distinct fact (behavior, dry-run, output destination, import step, criteria limitation, offline/online requirement). The core action is front-loaded in the first sentence, so an agent can quickly identify the 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?

With an output schema present, return values are covered. The description covers the main workflow, safety around dry-run, output location, and the Archicad dependency. Minor gaps remain for port and spec_id semantics, but they don't block correct invocation for the primary use case.

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 has 0% description coverage, so the description must carry parameter meaning. It meaningfully explains path (exported XML), spec_path (YAML spec), output, and dry_run (explicitly named). However, it never explains port or spec_id, leaving two of six parameters semantically undocumented.

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 opens with a specific verb and resource: 'Apply a YAML scheme spec to an exported schedule scheme XML' and lists concrete effects (set columns/order, retarget bindings, rename). This clearly distinguishes it from sibling tools like read_schedule_scheme and validate_schedule_scheme, which are read/validation operations.

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?

Provides clear context for use: it applies a spec to an exported XML, defaults to a dry run, and explains when Archicad must be open (Group/Name binding) vs fully offline (GUID-only binding). It does not explicitly name alternatives or say 'use read_schedule_scheme when you only need to read,' so it falls short of full when/when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only safety; the description adds concrete behavior: mutating commands are refused, parameters are validated against the bundled schema where available, and the command scope spans two API families. No contradiction with readOnlyHint or destructiveHint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three front-loaded sentences cover action, scope, restrictions, validation, and alternatives with no filler. The embedded documentation links are useful context rather than padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a generic command runner with an output schema, the description covers scope, restrictions, validation, and alternatives. It omits pointers to sibling discovery tools like list_api_commands or describe_api_command and the role of the optional port, but the provided links and output schema make it workable.

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 0%, so the description must compensate, but it only implies 'name' via 'by name' and never explains 'port' or the shape/meaning of 'params'. The generic 'params are validated' line does not provide per-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?

States it runs one read-only Archicad API command by name and returns the result, specifying both the official JSON API and Tapir add-on. This clearly differentiates it from execute_write_api_command and other dedicated 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?

Explicitly restricts to read-only commands, states write commands are refused and belong to execute_write_api_command, and instructs to prefer dedicated tools when available. This gives an agent clear selection criteria against the many sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark destructiveHint=true, but the description adds important behavioral detail: irreversibility for many commands, capability to reach DeleteElements and QuitArchicad, the confirm=true refusal behavior, and schema validation. This goes well beyond what the annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence earns its place: purpose, scope, danger, safety gate, and routing guidance. It is front-loaded with the core action and immediately warns about irreversibility.

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 is a generic command runner with high destructive potential, the description covers safety, validation, scope, and when to prefer dedicated tools. It could also mention using list_api_commands or describe_api_command to discover valid command names and schemas, but the included documentation links and output schema reduce that 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 0%, so the prose must compensate. It meaningfully explains `confirm` and the semantics of `params`, but `name` and `port` receive no explanation beyond their property names. The description partially compensates but does not fully document all four parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific action ('Run one Archicad API command') and an explicit effect ('changes the project'). It clearly distinguishes this from the sibling execute_read_api_command and from dedicated per-task tools, so an agent can tell what the tool is for.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Prefer the dedicated tools when one exists,' giving clear routing guidance to alternatives. It also scopes the tool to write-style API commands, though it does not explicitly name execute_read_api_command for read-only commands.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate destructive behavior, and the description adds concrete detail by stating the file is overwritten if it exists and that the Tapir add-on is required. It also clarifies that the export is aligned to the survey point, which is useful behavioral context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that packs in scope, destination, alignment, overwrite behavior, and the add-on prerequisite. Minor redundancy exists in 'at the given path,' but overall there is no meaningful fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter tool with an output schema, the description covers the essential behavior, destructive overwrite, alignment, and a prerequisite. The main gap is the undocumented optional port parameter, which is not compensated by the schema or description, leaving the tool slightly incomplete for nuanced calls.

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 0%, so the description must compensate for parameter meaning. It clarifies that bcf_path is the file destination, but leaves the optional port parameter completely unexplained; an agent cannot infer what port controls from either the schema or the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Export'), a precise scope ('every issue in the project'), and a concrete destination ('BCF file at the given path'). This clearly distinguishes it from the sibling import_issues_bcf and other issue-related 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 use case is clear: perform a full-project BCF export to a file path. It does not explicitly name alternatives or state when not to use it, but the scope and purpose are unambiguous enough that an agent can select it appropriately.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: server-side property reads, no API-side property filtering, coverage differences between whole-plan and model-elements-only, safety caveat that 0 is not proof of absence for 2D elements, and refusal of reads over the element ceiling. This goes far beyond the structured 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?

Dense but every sentence earns its place. The description front-loads the main grouping semantics, then covers property resolution, edge cases, return values, and performance constraints without repetition. The length is justified by the tool's complexity.

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 what the tool returns, when it can fail (ceiling refusal), how coverage affects interpretation of results, how to find property addresses, and how to structure groups. Combined with a rich input schema and output schema, nothing essential is missing for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite the schema adding field-level descriptions, the tool description compensates with critical semantics: groups combine with OR, inner comparisons use logical_operator, unary vs binary operator behavior, value units, and the no-usable-value edge case. It also tells the agent to call search_definitions for exact property addresses, which is essential for correct parameter construction.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Find elements matching criteria groups.' It clearly differentiates from siblings like search_definitions (finds property addresses) and get_element_data (reads element data) by focusing on criteria-based selection. The OR/group semantics make the tool's role unmistakable.

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?

Provides clear operational guidance: call search_definitions to resolve property addresses, and narrow with element_types, story, or classification to avoid ceiling refusals. It lacks an explicit 'when not to use' statement for alternatives like list_instances or get_element_data, so it falls just short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by stating exactly which aspects of element data are read (type, layer, properties, classifications), but it does not disclose any additional traits such as authentication requirements, rate limits, or pagination.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, dense sentence that front-loads the action and key outputs. Every clause adds value: the read scope, the property addressing syntax, and the optional classifications flag. There is no filler 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 read-only tool with annotations covering safety and an output schema explaining return structure, the description is largely complete. It covers the core required input and the optional parameter semantics. The only real omission is the meaning of 'port', but because it defaults to null and is not required for invoking the tool, the description remains sufficient for correct 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 description coverage is 0%, so the description carries the burden of explaining parameters. It adds meaningful guidance for 'properties' with the 'Group/Name' addressing convention, clarifies that classifications are optional, and implies 'guids' identify the elements. Only 'port' remains unexplained, but its default null and optional nature reduce the impact of that gap.

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 clear verb ('Read') with a specific resource ('element data') and enumerates exactly what is returned: type, layer, requested properties, and optionally classifications. It is specific and distinguishable from mutation tools like set_element_data, though it does not explicitly contrast with the similar sibling query_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 phrase 'for the given element GUIDs' implies when to use this tool: when you have element identifiers and need their data. However, it offers no explicit guidance about when not to use it, nor does it point to alternatives such as query_elements or list_instances, leaving some selection judgment to the agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint and destructiveHint annotations, the description discloses cost/safety behavior ('cheap and safe', 'can crash Archicad'), conditional refusal, scope semantics ('whole-plan' vs 'model-elements-only'), and a guarantee that by_type is always returned. This is rich, non-obvious 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 dense but every clause adds value: default behavior, cost warning, output semantics, and coverage caveat. It is front-loaded with the core verb and resource, though the later sentences are long and use parenthesis-heavy asides that reduce readability.

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 read-only aggregation tool with an output schema, the essential behavioral and safety caveats are covered, and the coverage field semantics are explained. The only material omission is port, especially because the input schema provides no description for it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

include_layer_story is well explained with consequences and default context, and the description clarifies output behavior for by_type and coverage. However, schema coverage is 0% and the port parameter is never described, leaving a meaningful gap for an agent deciding whether to set it.

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 opens with 'Aggregate element counts', a specific verb and resource, and immediately distinguishes itself from element-level tools by stating 'Counts only, never element data.' This clearly separates it from siblings like get_element_data and query_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?

It gives clear context: the default call is 'cheap and safe', and the optional include_layer_story flag is described as potentially expensive and refused on large models. It does not explicitly name alternative sibling tools or state when to prefer them, so it falls just short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds minimal behavioral context beyond noting that Tapir enriches the geolocation presence, but it does not disclose anything significant about side effects, prerequisites, or behavior not already implied by the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and the key output fields are listed up front. However, the parenthetical 'Tapir enriches' is cryptic and may confuse agents unfamiliar with that term, slightly reducing clarity.

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 that the tool has an output schema, no required parameters, and read-only annotations, the description covers the main purpose and result contents reasonably well. The main gaps are the unexplained port parameter and lack of sibling differentiation, but these are not fatal for such a simple 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 description coverage for the single 'port' parameter, and the description does not explain its meaning or usage. The parameter is optional and has a default of null, which reduces the risk, but the description still provides no guidance on what port refers to or how to set it.

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 identifies the resource as project info and enumerates the specific fields returned: Archicad version, project name, stories, hotlinks, and geolocation presence. It is not tautological and is sufficiently distinct from siblings like get_model_summary or query_elements, though it relies on the title for the verb.

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 gives no guidance on when to prefer this tool over alternatives or when not to use it. While the content implies it is for project-level metadata, there is no explicit context or comparison to sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the output type (GUIDs) and temporal state ('currently selected') but does not discuss side effects, permissions, or rate limits; however, none are expected for a read-only getter.

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 that front-loads the verb and result ('Return the GUIDs') with no filler. Every word earns its place.

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 read-only getter with an output schema available and no required parameters, the description is largely sufficient. The only remaining gap is the undocumented optional port parameter, but the default null allows a correct invocation without further knowledge.

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 only parameter, 'port', has no schema description and a 0% schema description coverage, and the tool description does not explain its meaning or when to override the default null. The parameter is optional and has a default, so the gap is mitigated, but the description provides no compensation for the missing 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 states a specific operation ('Return the GUIDs') on a clear resource ('elements currently selected in Archicad'), which unambiguously distinguishes it from sibling mutation tools like set_selection and clear_selection.

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 makes the read-only context explicit: it is for retrieving the current selection, not modifying it. It does not name alternatives like set_selection/clear_selection, but the 'currently selected' scoping gives clear context without exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false and destructiveHint=false. The description adds the Tapir add-on dependency and makes the visual side effect explicit. However, it doesn't disclose whether previous highlights are cleared, whether selection is affected, or if a visible view is required.

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 the core action front-loaded and the dependency placed parenthetically. No filler or repetition of the title.

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 visual operation with one required parameter, the description captures the essential purpose and prerequisite. However, the complete lack of parameter semantics for port and no notes on side effects make it less complete than an agent would ideally need. Output schema presumably covers return values.

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 0%, so the description must compensate. It implies rule_id selects the rule but doesn't explain how to obtain or format it. The optional port parameter is completely unexplained, leaving a significant gap for an agent trying to call the tool correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action ('highlight'), object ('elements failing a rule'), and location ('in the Archicad window'). This clearly distinguishes it from siblings like run_rule or create_issues_from_failures, which operate on failures differently.

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. The parenthetical '(requires Tapir add-on)' is a prerequisite, not a usage condition. No mention of using it after run_rule or choosing it over create_issues_from_failures.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already convey readOnlyHint=false and destructiveHint=true, and the description's 'Import issues' is consistent with a write/import operation. It adds some behavioral context with 'aligned to the survey point' and the Tapir add-on requirement, but does not explain merge, overwrite, or duplicate-handling behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single efficient sentence that front-loads the core purpose, then adds a prerequisite and an important alignment detail. Every phrase earns its place.

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 destructive annotations and an output schema, the description covers the main purpose, the required source file, and a prerequisite. Still, the port parameter and the operational impact (e.g., whether existing issues are modified or duplicated) are not addressed, leaving some 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 description coverage is 0%, so the description must carry parameter meaning. It indirectly clarifies bcf_path by mentioning 'a BCF file', but the port parameter is left completely unexplained despite being part of the input 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 a specific action ('Import issues into the project from a BCF file') and the resource being acted on. It also adds the alignment-to-survey-point detail, which helps distinguish this import tool from related tools like create_issue or export_issues_bcf.

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 — importing issues from a BCF file — and mentions the Tapir add-on prerequisite. However, it does not explicitly contrast with alternatives such as create_issue for individual issue creation or export_issues_bcf for the inverse operation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it covers both official JSON API and Tapir, emphasizes that the catalog contains ALL commands, and explains the read/write access filter's 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?

The description is a single, front-loaded sentence with no filler. It states the core purpose first, then the filtering parameters and their significance, making every part useful.

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 read-only listing tool with zero required parameters and an output schema, the description covers the essential invocation details and filter semantics. Minor gaps remain around the domain of valid group values and explicit pointers to sibling tools for per-command details, but the description is adequate for correct selection and basic 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 description coverage is 0%, so the description must compensate. It explicitly explains the access parameter with allowed values 'read' and 'write', and names group as a filter, but it does not enumerate valid group values or provide examples, leaving part of the parameter semantics undefined.

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 identifies the tool as a catalog of all available Archicad API commands, naming both official JSON API and Tapir. It distinguishes itself from sibling tools by explaining how filtering by access='read'/'write' reveals which execute tool runs a command.

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 gives clear context for when to use the tool: to browse or filter the full command catalog and to determine which execute tool applies. It does not explicitly mention describe_api_command as the alternative for details on a single command, so it stops short of full exclusion guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds no additional behavioral traits such as pagination, response format, or handling of invalid types. While simple, there is no extra transparency beyond what annotations supply, so a mid-range score is appropriate.

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 redundancy. The core action and type scope are front-loaded, and the list of valid types is directly useful. Every word earns its place.

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 adequate for a simple read-only list with an output schema present, but it lacks guidance on when to use it relative to siblings and does not explain the port parameter. These are notable gaps given the tool's low schema coverage and multiple competing list 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 description coverage is 0%, so the description must compensate. It provides concrete allowed values for the required attribute_type parameter (Layer, BuildingMaterial, Composite, Surface, Profile, ZoneCategory), adding value beyond the schema. However, it does not explain the optional port parameter, leaving a partial gap.

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') with a clear resource ('attribute names') and specifies the exact scope ('by type') with enumerated types. This distinguishes it from sibling tools like list_instances and list_rules, so an agent can immediately identify its function.

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 by listing attribute types and the required parameter, but it does not explicitly state when to choose this over alternatives like query_elements or get_element_data. There is no exclusions or alternative routing, making usage guidance only implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds useful behavioral context by naming exactly what information the tool reports, including Tapir add-on availability, which helps the agent interpret outputs and plan subsequent calls.

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 short sentences with no redundancy. The core purpose is stated first, followed by the one piece of usage guidance ('Call this first'). Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only discovery tool with a provided output schema, the description is complete. The agent knows what it does, what it returns, and when to invoke it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so parameter documentation is not needed. The description makes the no-input nature clear by focusing entirely on the read operation and its returned information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('List') and resource ('running Archicad instances'), and specifies the exact details returned (port, version, open project, Tapir add-on availability). This clearly distinguishes it from sibling tools that act on elements, issues, or API commands.

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 instruction 'Call this first' gives explicit timing guidance, establishing this as the discovery entry point before using other tools. It does not explicitly mention alternatives, but the tool's discovery role makes that less necessary.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'List' wording is consistent. It adds useful context beyond annotations by mentioning the Tapir add-on dependency and specifying that ids are returned. No contradictions.

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 succinct sentence that front-loads the action and resource, then adds the key dependency in a parenthetical. Every word earns its place and there is no redundant phrasing.

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 read-only list operation, the description covers the operation scope and prerequisite, and the presence of an output schema covers return details. The only notable gap is the unexplained optional port parameter, but its optionality and default null reduce the practical impact.

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 only parameter, port, has zero schema description coverage and the description never explicitly explains it. The Tapir add-on reference obliquely suggests it relates to the add-on connection, but the agent is left to infer the actual meaning of port. The description does not compensate for the missing schema 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 uses a specific verb and resource: 'List the issues in the open project', and even notes that ids are included. It is clearly distinguished from sibling mutation tools like create_issue, add_issue_comment, and export_issues_bcf because it is a read-only listing 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 gives clear context: this lists issues in the open project and requires the Tapir add-on. It does not explicitly name alternatives or state when not to use it, but the scope and prerequisite are 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context by specifying that the tool also reports rule-file load errors, which goes beyond the annotations. There is no contradiction between the description and 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 names the operation, the resource, the included fields, and the error-reporting behavior. Every part is informative and there is 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?

For a simple parameterless list tool with an output schema and read-only annotations, the description fully covers what the tool does and what it reports. Nothing essential 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?

The tool has zero parameters and an empty input schema, so there are no parameter semantics to document. The description instead clarifies the output content, which is appropriate for a parameterless listing tool.

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 starts with a specific verb and resource: 'List loaded QA rules'. It further clarifies scope by enumerating the output fields and mentioning rule-file load errors. This clearly distinguishes the tool from siblings like run_rule, which executes rules rather than listing them.

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 that this tool is used when you need to inspect loaded QA rules or see load errors, but it does not explicitly contrast it with alternatives. It does not mention run_rule or any other sibling as an alternative, so the usage context is only implied, not articulated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the tool as non-read-only and destructive, so the description's additional context is valuable: the tool refuses without confirm=true and the vector is interpreted in meters. There is no contradiction between the description and 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?

Two short sentences deliver the core behavior and the critical safety condition without filler. The wording is efficient and 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?

The description is mostly sufficient for a basic correct call: supply guids, a vector with x/y/z in meters, and confirm=true. It omits alternatives and optional port details, but the presence of an output schema reduces the need to describe return values.

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 0%, so the description must compensate for undocumented parameters. It explains vector's structure and confirm's role, but guids and port remain unexplained beyond their schema names and types, leaving significant gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific operation—moving elements via a relative vector—and adds useful detail about units and the confirmation requirement. It is not a tautology, but it does not explicitly differentiate itself from sibling mutation tools such as create_elements or delete_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 is given about when to use this tool versus alternatives, whether it applies to selected elements, or what prerequisites exist. The confirmation note is operational behavior, not usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation risk is communicated. The description adds the detail that this fires a publisher set by name, but does not mention side effects such as file generation or external publication. It does not contradict the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence and is appropriately front-loaded. The parenthetical '(Tapir)' adds a potentially useful API hint but is unexplained and may confuse agents unfamiliar with that term.

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?

While an output schema exists, so return format need not be explained, the description leaves important operational context uncovered: no side-effect disclosure beyond the destructive annotation, no usage guidance, and no explanation of the port parameter. For a destructive action with two parameters, this 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 description coverage is 0%, so the description must compensate. It clarifies that publisher_set_name identifies the publisher set, but it says nothing about the port parameter, its default, or its role. One of the two parameters remains effectively undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('fire') and a specific resource ('Archicad publisher set'), and identifies how the set is selected ('by name'). This clearly distinguishes it from sibling tools like run_rule or execute_write_api_command, which operate on different resources.

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 gives no guidance about when to use this tool versus alternatives, no prerequisites, and no exclusions. An agent cannot infer from the description why publish would be preferred over run_rule or other action-oriented tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true and destructiveHint=false, and the description adds an important behavioral detail: 'Reads the file only, never Archicad.' This goes beyond the annotations by clarifying that the tool does not interact with the Archicad application at all.

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 three sentences, front-loaded with the core purpose, then the prerequisite workflow, then a clarifying limitation. No sentence is wasted and the structure is easy to parse for an agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple: one required parameter, an output schema exists, and annotations cover safety. The description adds the necessary background about why export is required, how to do it, and that the tool only reads a local file. Nothing essential is missing for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It does so by explaining that the path is the file path of an exported schedule scheme XML, including the export prerequisite. It does not specify path format or absolute/relative requirements, but for a single 'path' string parameter this is reasonably sufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Describe'), a specific resource ('exported Archicad schedule scheme XML'), and the exact content of the result ('criteria and its ordered columns, with what each column binds to'). This clearly distinguishes it from sibling tools like edit_schedule_scheme and validate_schedule_scheme.

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 gives clear context: schedules have no API, so the user must export the scheme via a specific menu path and pass the file path. It also clarifies the read-only file operation. It does not explicitly name alternatives or state when not to use it, but the workflow guidance is strong.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description reveals detailed behavior beyond annotations: the confirm-gated split between would_release/not_mine/not_found and released/still_mine, plus the important guarantee that unsent changes are not lost. This strongly compensates for the generic destructiveHint=false annotation.

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 compact and every sentence adds value: purpose, dry-run vs confirmed behavior, result categories, and non-destructive guarantee. It front-loads the core intent and then layers necessary operational detail.

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 output schema exists, the description need not list return fields. It covers behavior, confirm semantics, and safety guarantees well. The main gap is not addressing the port parameter or explicitly contrasting with sibling release/reserve/delete operations, but overall the tool is understandable enough to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The confirm parameter is thoroughly explained, and guids is inferable from the command. However, the port parameter is left undocumented, and since schema description coverage is 0%, the description does not fully compensate for the missing parameter details.

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 opens with a specific verb and resource: 'Release elements from your Teamwork workspace (Tapir).' This is clear and distinct from delete/reserve, though it does not explicitly name a sibling to distinguish it from.

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 confirm-gated usage is well explained: without confirm=true it dry-runs, with confirm=true it actually releases. However, there is no explicit guidance on when to choose this over related tools like reserve_elements or delete_elements; usage context is implied rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description richly discloses behaviors beyond annotations: the confirm gate, the preflight results, the impossibility of reading other users' locks without attempting, the reserved_by_others and indirectly_reserved statuses, and the visible blocking effect on teammates. This goes well beyond the annotations' simple readOnlyHint/destructiveHint flags.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence adds essential information: purpose, confirm behavior, why attempts are required, result statuses, indirect reservations with an example, and the blocking consequence. It is front-loaded with the core purpose and uses formatting like 'CONFIRM-GATED' to make the key behavioral switch prominent.

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 tool's complex confirm-gated behavior, result variants, side effects, and visibility rules, which is strong for a 3-parameter tool with an output schema. The only notable gap is the complete absence of port semantics and any mention of prerequisites, such as needing an active Teamwork connection.

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 0% description coverage, so the description must compensate. It does a good job for confirm, explaining that confirm=true triggers actual reservation and listing the resulting statuses, and it implies guids identify the elements to reserve. However, port is never mentioned, leaving one of three parameters semantically unexplained.

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 opens with a clear verb and object: 'Reserve elements in a Teamwork project so you can edit them.' This is specific and distinguishes the tool from siblings such as release_elements and set_element_data, while the parenthetical '(Tapir)' anchors it to a known workflow.

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 explains the two usage modes: without confirm=true it performs a safe preflight, and with confirm=true it actually reserves. It also gives the behavioral reason why attempting is necessary to learn about others' reservations. It does not explicitly name alternative tools or state when not to use this tool, so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by stating the return shape: a verdict of pass/fail, failure count, and failing element GUIDs, which goes beyond the annotations and helps the agent anticipate the result.

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 front-loads the action and resource, then states the output. It contains no filler or redundant restatement of the title.

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 is simple, read-only, and has an output schema, so the description adequately supports basic invocation with rule_id. However, it is incomplete in two areas: the optional port parameter remains unexplained, and there is no guidance about when to choose this tool over closely related QA sibling 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 description coverage is 0%, so the description must compensate for the two parameters. It only clarifies 'rule_id' indirectly through 'by id' and offers no explanation of the optional 'port' parameter, leaving its meaning and effect on the call ambiguous.

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-resource pairing: 'Run one QA rule by id.' It clearly scopes the operation to a single rule and distinguishes it from sibling tools like list_rules, highlight_failures, and audit_delivery_readiness, which involve listing, highlighting, or auditing rather than executing one rule.

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 gives no guidance on when to use this tool versus related siblings such as highlight_failures or create_issues_from_failures. There are no exclusions, prerequisites, or alternative recommendations, leaving the agent to infer usage from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint=true and destructiveHint=false. The description adds substantial behavior beyond that: case- and accent-insensitivity, ranking orter (whole-word → word-start → substring, with the 4-letter minimum rule), pagination via total_matches/next_offset, and the key reassurance 'Reads definitions only, never property values'. It also discloses output units (m, m2, m3, radian) and match result fields. Nothing contradicts the read-only 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?

Long, but every sentence earns its place given 0% schema coverage and rich output semantics. It is front-loaded with purpose, then matching, per-parameter semantics, output contract, ranking, pagination, and finally safety. No filler, repetition of the title, or restating of annotations; the density is justified by the information load.

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 7-parameter fuzzy search with an output schema, the description covers match semantics, per-parameter meaning, result fields with units, ranking order, pagination mechanics, and a safety statement. An output schema exists, so return values needn't be spelled out — yet this goes beyond. Remaining gaps are 'port' semantics and any note on empty/no-match results, which are minor against this coverage. A 4 reflects that near- but not fully-complete state.

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 0%, so the description must carry the semantics and largely does: kind gets its allowed values with examples, alternatives gets its count and translation use-case, editable_only gets its workflow caveat, and offset/limit are covered by the next_offset pagination sentence. query is implicit in the search framing. Only 'port' receives no explanation, and 6 of 7 parameters are meaningfully enriched. The gap on port prevents a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: 'Fuzzy search over property and attribute definitions', and explains the purose — 'a caller does not need to know the exact Group/Name'. This distingushes it from sibling element-search and value-access tools (find_elements, get_element_data) by making clear it searches defintions, not instances. The title and description align precisely.

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 opening line gives the trigger context: use this when you don't know the exact Group/Name. It also routes workflow with siblings: 'check it before set_element_data' for editable_only, and the output 'property' field is 'the exact address find_elements, get_element_data, set_element_data and rules accept'. Missing an explicit when-not-to-use statement (e.g., if you already know the exact address, call the data tools directly), which prevents a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the destructiveHint annotation, the description adds important behavioral context: it explains the default dry-run behavior, that it returns planned changes (current -> new), and which flag commits. This is valuable safety-relevant behavior not visible from the schema or annotations alone.

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, with the most important safety behavior (dry-run by default) front-loaded. Every sentence adds value and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Although an output schema exists, the input side is under-specified. The agent knows the tool's intent and dry-run mechanism, but the required 'changes' structure and the optional 'port' semantics are missing. For a mutating tool, this is a significant gap that could lead to incorrect calls.

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 0%, so the description carries the burden of explaining parameters. It explains dry_run well, but the required 'changes' parameter is left completely underspecified—an array of objects with arbitrary additional properties—and 'port' is not explained at all. An agent cannot reliably construct a valid request payload from this definition.

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 operation: 'Write element property values.' It identifies the resource (element properties) and the action (writing/setting), and the dry-run behavior distinguishes it from sibling read-only tools like get_element_data. This is specific enough for an agent to select the right category of tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear operational guidance: it explicitly states that the tool runs in dry-run mode by default and that dry_run=false commits changes. It does not explicitly name alternatives or when-not-to-use conditions, but the write-vs-read distinction from sibling tools is reasonably obvious.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations, the description discloses that the current selection is fully replaced and that previous hand-selected items are deselected. This is a meaningful side-effect disclosure. It does not address invalid GUID behavior or persistence, but it covers the main behavioral surprise.

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 short, front-loaded sentences with no filler. The core action is stated first, and the additional side-effect about deselecting prior hand-selected items is conveyed in a second concise 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?

For a simple selection setter, the description covers the core behavior and the meaning of the required parameter. The main omission is port semantics, though port is optional and the output schema plus annotations provide some surrounding context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds domain meaning to guids by calling them 'element GUIDs', which helps beyond the raw schema. However, the optional port parameter is left completely unexplained, and with 0% schema description coverage the description does not fully compensate for that gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('replace') with a clear resource ('current selection') and mechanism ('given element GUIDs'). It also explicitly notes that any hand-selected items are deselected, which clearly distinguishes it from get_selection and clear_selection.

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 the tool is used when the agent wants to set or replace the current selection with specific GUIDs, but it never explicitly contrasts this with get_selection or clear_selection. No when-to-use or when-not-to-use guidance is provided beyond the implied purpose.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds valuable behavioral context by stating it reads property definitions only, not values, and therefore avoids the property-read crash. It also discloses exactly what validations are performed, which goes beyond the structured 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 two compact sentences with the main action front-loaded and no wasted words. The safety-related note earns its place by explaining why this validation is safe to call.

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 is simple, has an output schema, and the annotations cover the read-only/destructive profile. The description covers the core behavior and safety context. The main gap is the lack of parameter semantics for path and port, but the overall definition is still reasonably complete for a read-only validation 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 0% description coverage, and the description does not explain the meaning of 'path' or 'port'. It provides context that the tool operates on an exported schedule scheme, but it does not compensate for the undocumented parameters, especially the optional 'port' parameter.

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 ('Check') and identifies the exact resource ('an exported schedule scheme against the open project') with two concrete validation criteria: property binding existence and column caption agreement. This clearly distinguishes the tool 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this tool is for validating a scheme rather than reading or editing it, but it does not explicitly state when to choose it over alternatives or mention sibling tools. The usage context is understandable but left mostly to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds useful behavioral context by specifying that only IFC-related QA rules are run and that the Tapir add-on is required. It doesn't describe details like whether the rule set is dynamic, but the output schema covers result 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?

Two sentences with no filler. The main purpose is front-loaded, and the prerequisite is stated separately. Every sentence earns its place, and the description is appropriately sized for the tool's simplicity.

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 purpose and a dependency, and the output schema exists, but it completely omits the 'port' parameter semantics. For an agent to invoke the tool correctly in all cases, it needs some indication of what 'port' controls. The description lacks this, leaving the definition incomplete despite the tool having just one parameter.

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 0%, yet the description does not mention the 'port' parameter at all. Even though the parameter is optional, the description provides no meaning for it, leaving the agent to guess whether or how to supply a port. This is a significant gap given the 0% schema 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 states a specific verb ('Run') and resource ('IFC-related QA rules'), and the intended outcome ('check IFC export readiness'). The word 'only' clearly distinguishes this from broader QA/audit tools like audit_delivery_readiness, making the tool's scope 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 clearly implies when to use the tool: when you need to verify IFC export readiness rather than general delivery readiness. It also notes a prerequisite (Tapir add-on). However, it does not explicitly state when not to use it or point to alternatives like audit_delivery_readiness for non-IFC checks.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.