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 only declare readOnlyHint=false and destructiveHint=true; the description adds substantial behavioral detail beyond that, including the safe dry-run default, that drape follows surface cross fall with nodes added until within drape_tolerance, that lift raises the marking, and that update_guid keeps prior settings. This is exactly the mutation/safety context an agent needs.

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

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

Purpose is front-loaded and every clause conveys information, but the body is a single dense paragraph chained with semicolons that is heavy to parse. Given the tool's complexity the density is defensible, though some grouping would improve 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?

An output schema exists so return values need not be explained, and the description covers the core workflow: path sourcing, draping, and the dry-run/update lifecycle. The undocumented half of the parameters is the main residual gap for a 21-parameter tool with no annotation detail on them.

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?

With 0% schema description coverage across 21 parameters, the description carries the full burden and explains the semantically hard ones well (source_guid vs points, marking presets, the stripes/bays/lettering sub-fields, drape_on, drape_tolerance, lift, update_guid, dry_run). Roughly ten parameters remain opaque (thickness, flip_sides, pattern_align, pattern_shift, paint_surface, slope_percent, whole_dashes, start_height, port, path_tolerance), so compensation is strong but not exhaustive.

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 names a specific verb (Place) and resource (Road Marking), enumerates the marking types it covers (lane lines, zebra crossings, bays, lettering) and states exactly what it produces (the 'Road Marking' library part draped onto Meshes and Slabs). No sibling tool overlaps this scope, so an agent can distinguish it immediately.

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

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

It clearly explains the operational path: dry-run by default, pass dry_run=false to place, and use update_guid to rewrite a placed marking. It does not contrast itself against alternates like create_elements or create_swept_beam, so there is context but no explicit 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?

Despite annotations already flagging destructiveHint, the description adds substantial behavior: dry-run is the default, update_guid preserves the GUID while profile/offsets/flip/end cuts stay unless specified, node roll resets to 0, and cut angles have documented ranges and directional meaning. This is unusually rich disclosure for a mutation tool.

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

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

Dense but front-loaded, opening with the object and path sources before drilling into profile, update, cuts and reference-line options. The single long block is justified by 18 parameters, though slightly better structuring would aid scanning.

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 complex 18-parameter mutation tool with an output schema available, the description covers construction logic, update semantics, units, ranges and the dry-run report contents. An agent has everything needed to call it correctly without opening the schema.

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

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

Schema coverage is 0%, so the description carries the full burden and mostly succeeds: it gives units (metres, degrees), ranges (-80 to 80, -85 to 85), defaults (0.2 x 0.2 rectangle), and meaning for source_guid, points, start_height, slope_percent, profile, update_guid, ref_line, ref_offset, and all four cut parameters. Only path_tolerance, port and the offset_u/offset_w pair are left undefined, which is a minor gap given the breadth covered.

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 ('Place a Swept Beam') and immediately defines what the object is (sloped, curved beam with a profile or rectangle) and which library part it becomes. Distinguishes itself from generic siblings like create_elements by naming the exact BIM construct.

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?

Explains when to use which path source (flat source with start_height/slope_percent vs morph lines/points keeping their own heights) and how update_guid converts the call into an update of an existing beam. It lacks explicit routing to alternative sibling tools, but the create-vs-update split is clear.

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?

Goes far beyond the destructiveHint=true / readOnlyHint=false annotations: it declares IRREVERSIBILITY, the confirm gate, the active-window-only deletion semantics, the fact that refused elements are silently excluded, the read-back verification, and the exact reasons an element may be skipped (other view, hidden layer, Teamwork reservation, locked, hotlink). This is unusually rich behavioral disclosure for a destructive tool.

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

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

Front-loaded with the essential facts ('Delete elements. IRREVERSIBLE. Refuses without confirm=true.') and contains no filler. The final run-on sentence enumerating return fields is dense and partially redundant with the existing output schema, which slightly dilutes its efficiency.

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, irreversible tool with an output schema, the description supplies everything an agent needs: the safety gate, scope limitations, silent-skip behavior, and verification. Nothing material is missing.

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

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

Schema description coverage is 0% for 3 parameters, so the description must compensate. It explains the semantics of confirm well (must be true or the call is refused) and implies guids are the elements targeted, but the port parameter is never mentioned and guids get no format/scope detail.

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 ('Delete elements') that an agent can immediately distinguish from mutating siblings like release_elements or reserve_elements. It does not, however, explicitly call out which sibling to prefer in ambiguous cases, so it stops short of a 5.

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

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

Gives one concrete precondition ('Refuses without confirm=true'), which is genuine usage guidance, but never states when to choose this over alternatives such as release_elements or set_element_data, nor any exclusion beyond the confirm gate.

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?

This is the standout dimension. Annotations only say readOnlyHint=false and destructiveHint=true; the description adds the critical non-obvious fact that the tool is DRY-RUN BY DEFAULT and requires dry_run=false to actually commit. It also discloses that items keep their GUID so classified elements and property availability remain attached, and that reparenting an item is unsupported.

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

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

Front-loaded with purpose, then the highest-stakes operational detail (dry-run default), then the payload formats. Given 0% schema coverage, the inline JSON examples are load-bearing rather than filler, and there is no redundant prose.

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?

An output schema exists, so return values need not be described. For a destructive mutation tool the description covers the safety-critical behavior, payload shape, and a key limitation (no reparenting). Minor gaps remain: whether a committed edit is reversible and what the undocumented 'port' parameter does.

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 burden, and it does: it documents dry_run's default/commit semantics and gives explicit JSON shapes for both item and system change objects, including optional fields like code, name, description, source, version and date format. The 'port' parameter is left undocumented, which is the only 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 opens with a specific verb+resource: 'Edit classification systems and items in place.' This is clearly distinguishable from siblings like edit_property_definitions and edit_schedule_scheme, which operate on different domains. It stops short of naming an alternative tool explicitly, but the resource scope is 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?

Usage is implied rather than stated: the agent learns it should pass dry_run=false to commit, and that moving an item to another parent is not supported. However, there is no explicit 'use this when...' or naming of alternative tools for related edit tasks, so guidance is only partial.

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?

With destructiveHint=true already set, the description goes well beyond annotations: dry-run returns before/after plus warnings, GUIDs are preserved so element values survive except when removing an option (elements show <Undefined>) or availability, and it names the required 'Tapir build with UpdateClassificationItems'. This discloses side effects and prerequisites richly.

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 most decision-relevant facts (in-place scope, dry-run default) are front-loaded, followed by addressing rules and an example. Dense but every clause earns its place; no filler.

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

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

For a destructive, three-parameter mutation tool with an output schema present, the description covers scope, commit behavior, addressing syntax, side effects on element values, and the environment prerequisite. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 0%, so the description must carry parameter meaning, and it does: dry_run semantics, full addressing grammar for 'Group/Name' vs GUID, availability 'System/Code' syntax with '/*', enum option addressing, and a concrete changes example. Only the shared 'port' param is left undocumented, a minor 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?

States a specific verb and resource ('Edit custom property DEFINITIONS in place') and immediately disambiguates scope with '(not element values)'. This cleanly separates it from siblings like set_element_data, edit_classifications, and import_definitions, so an agent can pick the right tool without opening schemas.

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

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

Explains the default dry-run workflow ('pass dry_run=false to commit') and routes the agent to search_definitions for addressing. It does not explicitly contrast with import_definitions or state when NOT to use in-place editing versus a bulk import, so it stops short of full alternative routing.

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?

With readOnlyHint/destructiveHint already covering safety, the description adds substantial non-obvious behavior: property comparisons are evaluated server-side (no API-side property filtering), oversized reads are refused, elements with no usable value match no binary operator, and the returned 'coverage' flag reveals that without Tapir, 2D elements are invisible and a zero count is not proof of absence. These are exactly the traps an agent needs warned about.

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 dense paragraph that is front-loaded with the group/comparison semantics. Every sentence carries operational information, though the single block of prose would be easier to scan if the return-shape and coverage caveats were split out.

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?

An output schema exists, yet the description still adds value by flagging the coverage caveat (2D elements invisible without Tapir) and the read ceiling. The main omission is any explanation of selection_only, which an agent may reasonably expect to control selection 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?

Top-level schema description coverage is 0%, and the description explains the nested structure well (groups OR together, comparisons combine via logical_operator, is/is_not type restriction, {property, operator, value}). However it never mentions the top-level 'selection_only' or 'port' parameters, leaving their effect undocumented in both the schema and 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?

States a specific verb and resource ('Find elements matching criteria groups') and immediately defines the criterion structure, so the agent knows this is a property/type-based query rather than a lookup by GUID (get_element_data) or a read of the current selection (get_selection). It also names the companion tool search_definitions for resolving property addresses.

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

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

Gives actionable context: call search_definitions to find a property's exact address, and narrow with element_types, story or classification before a property read or the call is refused for exceeding the element ceiling. It routes to an alternative tool but does not state when to prefer a sibling query tool instead of this one.

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?

Beyond the annotations' readOnlyHint and destructiveHint, it discloses important behavioral nuance: the returned 'coverage' value depends on whether the Tapir add-on is active, and without it selected markers, 2D elements, and native MEP routes are omitted, so an empty list is not conclusive.

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 states the core return value first, then adds the coverage caveat. It is dense but every part earns its place, with 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?

An output schema exists and annotations cover the safety profile, so the description need not explain return values in general. It adds the key coverage caveat, but the optional 'port' parameter remains entirely undocumented.

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% and the description never mentions the single optional 'port' parameter, leaving its meaning and effect undocumented. The description therefore fails to compensate for the schema gap on the only 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?

States a specific verb and resource: 'Return the GUIDs of the elements currently selected in Archicad.' It clearly distinguishes itself from siblings like set_selection and clear_selection by focusing on reading the current selection rather than modifying it.

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 the tool is useful (when the current selection is needed) and adds a usage caveat about empty lists not proving no selection, but it does not explicitly name alternatives such as set_selection or clear_selection.

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 declare destructiveHint=true, and the description delivers the context that makes that risk actionable: dry-run by default, what the conflict policy does, and the exact values each policy accepts. This is richer behavioral disclosure than the annotations alone provide, with no contradiction.

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

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

Three tight sentences, front-loaded with the resource and the dry-run default, followed by policy details. Dense but every sentence carries information; the conflict enumeration is slightly compressed but readable.

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?

An output schema exists so return values need not be detailed, yet the description still summarizes commit output (created/removed). Combined with kind and conflict semantics, an agent has enough to call it correctly; only the undocumented 'port' and lack of a stated when-to-use condition leave small gaps.

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

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

Schema coverage is 0%, so the description must carry parameter meaning, and it does a lot: kind values, per-kind conflict enums, item_conflict values, and the dry_run default. The 'port' parameter is never mentioned, which is the one 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?

States a specific verb and resource ('Import a Property Manager ... or Classification Manager ... XML file') and distinguishes the two operating modes by kind, so the agent knows exactly what the tool acts on. It does not explicitly differentiate itself from closer siblings like edit_property_definitions or import_issues_bcf, keeping it short of a 5.

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

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

The description makes the operating context plain: dry-run is the default, and it tells the agent what the dry-run reports (new vs colliding names) and what committing returns. It still does not state when to prefer this over direct definition editing, so no explicit exclusions are given.

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?

Beyond the destructiveHint annotation, it discloses the gating confirmation flag, the active-window database scoping rule, and a concrete enumeration of refusal reasons (another view's, hidden layer, not reserved in Teamwork, locked, hotlinked module, not found). It also describes the result partitioning (requested/moved/not_moved with GUIDs/active_window), which is rich behavioral context an agent could not infer from 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 sentences, front-loaded with the action and the confirmation gate, then refusal conditions, then return shape. Dense but each sentence carries information; the final return-format sentence is the weakest since an output schema exists.

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, multi-parameter mutation with a nested vector argument, it covers the confirmation requirement, scoping constraints, and failure modes well. It redundantly restates return fields that an output schema already defines, and leaves the port parameter unexplained, keeping it just below 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% and vector is an opaque additionalProperties object in the schema, so the description carries real weight: it specifies the vector shape and unit (x,y,z meters) and the semantics of confirm=true. guids and port are only implicitly covered, so it does not fully compensate for the coverage gap, but it adds substantial meaning over the schema.

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

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

The description opens with a specific verb and resource plus the exact parameterization semantics: "Move elements by a vector {x,y,z} in meters." That is far more informative than the name/title alone and distinguishes it from siblings like set_element_data or create_elements. It stops short of naming an alternative tool for cases where a different move mechanism applies, so it misses the top tier.

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 states a clear precondition ("Refuses without confirm=true") and defines the operational context in which the tool applies (elements in the active window's database), which effectively tells the agent when the tool will and won't act. It does not name competing siblings or draw explicit use-versus-avoid boundaries, so it falls 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=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?

Annotations only declare destructiveHint=true; the description adds the crucial safety behavior that nothing is written unless dry_run=false, plus the full result taxonomy ('applied', 'failed' grouped by code/message, 'skipped' with the precise reasons an element is not editable, and partial 'stopped' batches). This is exactly the behavioral disclosure annotations cannot carry.

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

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

Front-loads the dry-run default and keeps everything in one dense but readable passage. The long parenthetical enumerating skip reasons is slightly heavy but each clause conveys distinct, actionable information.

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?

An output schema exists, so return shapes need not be spelled out, yet the description still enumerates status outcomes, which is helpful. The remaining gap is the structure of the 'changes' payload, which an agent needs in order to actually 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 explains dry_run's default and effect well, but the required 'changes' array (items of free-form objects) and the 'port' parameter are never defined, leaving the core payload semantics 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?

States a specific verb and resource: 'Write element property values.' This cleanly separates it from the read counterpart get_element_data in the sibling list, and an agent can tell what the tool does 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?

Gives clear operational guidance: dry-run is the default and returns planned changes, and dry_run=false commits. It does not name alternative tools or describe when to prefer them, but the when-to-commit context is well covered.

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.