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?

Goes well beyond the annotations (destructiveHint=true) by enumerating exactly which properties a favourite takes over (wall height/top link/reference line/structure, door-window library part/size/sill, layer), which elements are skipped and why, and what is and is not read back. Slight deduction because this critical safety detail is buried in a dense run-on sentence rather than surfaced first.

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?

Information-dense and roughly front-loaded (purpose, then DRY-RUN BY DEFAULT), but delivered in very long run-on sentences with repeated items in the skip list (locked appears twice) and version caveats interpolated mid-sentence. It rewards careful reading but does not earn every word.

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

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

Covers the mutation, dry-run safety, skip reasons, version-dependent behaviour, keep semantics, readback coverage, and the to_defaults edge case; an output schema exists and the description still summarizes the return shape (applied, changed, unchanged, failed, restored). Nothing an agent needs to call 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?

With 0% schema description coverage and 10 parameters, the description carries the burden and mostly succeeds: it explains keep (with its accepted values and version caveats), dry_run, favorite, settings, classifications, categories, properties, to_defaults, and guids by implication. Only `port` goes completely undocumented, keeping it just short of 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 and resource: make existing elements match a favourite (Tapir) in one step. It also contrasts behavior with the sibling modify_elements for older Tapir versions, so an agent can distinguish it from neighbouring mutation tools 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?

Explicitly states the dry-run default, what happens when no favourite is supplied (nothing changes; it lists candidate favourites), and names the alternative route (modify_elements on Tapir <1.7.3 for heights/sizes). The to_defaults=true with no guids branch is also called out as a distinct mode.

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?

Goes well beyond the readOnlyHint/destructiveHint annotations: discloses the 1568-pixel downscaling cap and the scaled_from field that reports the original size, the Tapir 1.7.2 version requirement, and how entire_drawing changes what is framed. The 'Reads only' line reinforces rather than contradicts the annotations. This is exactly the kind of operational context 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?

Purpose is front-loaded in the first clause, followed by use case, prerequisite, option semantics, scaling behavior, and version requirement in four tight sentences. Every sentence adds information an agent needs; nothing is redundant.

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

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

For a 2-parameter read tool with no output schema, the description covers what is returned (an image), the scaling caveat, and the environment prerequisite. It is only incomplete on the port parameter and on how/where the image is delivered, which keeps it from the top score.

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

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

Schema description coverage is 0%, so the description must compensate for both parameters. It fully explains entire_drawing ('covers the whole drawing of a 2D window instead of the current zoom') but says nothing about the port parameter, leaving half the inputs 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 concrete verb and resource (capture the current Archicad window as an image) and enumerates the view types it can show (floor plan, section, 3D, layout). It also distinguishes itself from the visual-workflow sibling by pointing to show_elements as the setup step, so an agent can tell it apart from pure data reads like get_element_data or get_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?

Gives an explicit when-to-use rationale ('to check a result by eye' with examples such as door swing direction and wall junctions) and a prerequisite workflow ('Call show_elements first to bring the elements into view'). It lacks any when-not-to-use or exclusion, so it falls short of the top band.

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 only declare readOnlyHint=false and destructiveHint=true, while the description adds substantial behavioral context: full validation before sending, skipping of invalid items with reasons, host-existence and editability requirements, warning conditions, partial-success return structure, and placed_not_set behavior. This goes far 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 content is information-dense and front-loaded with purpose, but it is a single sprawling paragraph with many long clauses. It could be structured into sections (types, dry-run behavior, library parts, sketches, returns) to improve scanability without losing meaning.

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 complex, has four parameters, 0% schema descriptions, and an output schema, the description supplies extensive missing context: element types, validation behavior, warning conditions, partial-failure return shape, and downstream correction workflow. It is complete enough for an agent to call 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 coverage is 0%, so the description must compensate. It thoroughly explains element_type with a long type list, explains items field conventions, units, the items=[] schema-discovery pattern, and dry_run's default behavior. The port parameter is not mentioned at all, so it is not fully complete.

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 ('Create elements'), then enumerates exactly which Archicad element types are supported. It clearly distinguishes itself from modify_elements and learn_library_part by describing creation semantics and the dry-run validation 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?

Gives explicit when-to-use guidance: dry-run by default, pass dry_run=false to actually create, use items=[] to retrieve the item schema, learn a library part before placing by placement, and capture_window plus modify_elements after creation. It also names the correct alternatives for learning parts and correcting mistakes.

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?

Goes well beyond the annotations: discloses that it is dry-run by default and only writes when dry_run=false, that update_guid preserves GUID/profile/offsets/flip/end cuts and resets node roll, the numeric ranges for cut angles, and what the dry-run report contains. That is exactly the extra behavioral context the destructiveHint alone cannot convey.

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 purpose, and nearly every sentence adds real information (sources, profile default, update preservation rules, dry-run). However it is a single dense paragraph with no bullets or breaks, and the end-cut sentence is hard to parse on first read.

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-value explanation is rightly omitted, and the dry-run report contents plus safety profile are covered. For an 18-parameter geometry tool it is close to complete, with only port, path_tolerance and offset_u/offset_w left undocumented anywhere.

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 18 params, the description carries the burden and mostly delivers: it defines source_guid source types, points format and units, start_height/slope_percent applicability, the profile object shape and default, end-cut angles with ranges and direction, and ref_line/ref_offset semantics. Gaps remain: port, path_tolerance, and the directional meaning of offset_u/offset_w are never explained, and flip is only named in passing.

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?

Opens with a specific verb and resource: 'Place a Swept Beam: a sloped, curved beam with a Profile Manager profile or a rectangle, as the "Swept Beam" library part.' An agent knows exactly what is produced. It does not name a sibling (e.g. create_elements) for the generic case, so it stops short of explicit sibling differentiation.

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

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

Gives clear operational context: path comes from source_guid OR points, update_guid rewrites an existing beam instead of creating, and dry_run=true is the default. This tells the agent which mode to pick. No explicit 'use X tool instead when Y' routing against siblings, so not 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?

Goes well beyond the destructiveHint annotation: irreversibility, the confirm gate, Archicad's silent-success quirk for out-of-window elements, the read-back verification step, and the enumerated refusal reasons all add real operational context an agent needs before calling.

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 critical warning ('IRREVERSIBLE') and confirm requirement; dense but every clause carries information. The long middle sentence is run-on but not wasteful.

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

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

Despite an existing output schema, the description explains the notable return fields (requested, deleted, not_deleted grouped by reason, active_window, stopped), so an agent understands both how to call it and how to interpret partial failures.

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 semantics. It fully explains confirm's required value and clarifies that guids are filtered to those actually deletable, substantially compensating for the gap; only the port parameter is left 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?

Starts with a specific verb+resource ('Delete elements') and immediately disambiguates from siblings like modify_elements/move_elements by scoping what actually gets deleted. An agent can tell exactly what this does from the first sentence.

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?

States the hard precondition (refuses without confirm=true) and explains the active-window scoping rule that determines when deletion will silently not apply. It doesn't name an explicit alternative tool, but the usage context is unambiguous.

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

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

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

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

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

The description is two short sentences with no filler. The purpose is stated first, and the crucial usage instruction follows immediately, making it easy for an agent to parse and act on.

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

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

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

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

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

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

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

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

The description clearly states the tool's function: retrieving the full description and input schema for a single API command. It also distinguishes itself from the execution tools by explicitly saying to call it before execute_read_api_command or execute_write_api_command.

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

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

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

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

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

Annotations declare destructiveHint=true/readOnlyHint=false, and the description is consistent while adding substantial beyond-schema context: create never overwrites, unspecified modify fields keep their values including ones Tapir's own overwrite would drop, writes cannot be undone, and pre-flight skips are explained with reasons (elements on a deleted layer, floor plan not active, index-1 attributes). Teamwork reservation and the commit result shape (applied/not_applied/failed/stopped) are also disclosed.

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: the verb/resource and the dry-run default come first, then the change-shape grammar. It is a single long block where bullet-style separation of the three action shapes would aid scanning, but no sentence is 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 multi-mode mutation tool, the description covers preconditions (Teamwork reservation, active floor plan), irreversible effects, per-mode semantics, and commit return groups — more than enough even though an output schema exists and would have excused omitting return details.

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% and the changes array is untyped free-form objects, so the description carries the full burden — it does so well by documenting the action-key shape, Tapir field names/units, and reference-by-name rules for foreign-key fields. The only gap is that the port parameter is never mentioned.

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?

Opens with a specific verb set (create/modify/delete) plus the resource, and enumerates the attribute types covered (layers, composites, surfaces, pen tables, etc.). It is clearly distinguishable from siblings like set_element_data, edit_property_definitions, and list_attributes, which handle different object domains.

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

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

Explicitly states the dry-run-default/safe-vs-commit protocol, points to changes=[] for field discovery and list_attributes(details=true) for current values, and names reserve_elements (object_sets) as the Teamwork prerequisite. When-to-use and alternative routing are both 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 the annotations (readOnly=false, destructive=true), it discloses the critical safety behavior: writes are staged by default and only committed with dry_run=false. It also explains the consequence of the edit — GUIDs persist so classified elements and property availability stay attached — and names the dependency on reserve_elements.

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 dry-run default, which is the single most important fact, and every subsequent sentence adds operational information. Density suffers slightly from inline JSON snippets and the terse 'reserve_elements object_sets' reference, which reads as internal shorthand.

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, and the description covers the mutation semantics, the payload shape, and the Teamwork prerequisite. The unaddressed `port` parameter and the vague contrac for malformed `changes` entries keep it short of full completeness for a destructive write 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?

With 0% schema description coverage, the description carries the burden and largely does: it lays out the shape of each entry in `changes` for both items and systems, including the date format (YYYY-MM-DD) and optional fields. The `port` parameter is never mentioned, and the item/system objects remain loosely typed (additionalProperties: true), leaving residual ambiguity.

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 ('Edit classification systems and items in place'), which separates it cleanly from edit_property_definitions and edit_attributes by resource. It never explicitly names those siblings, so an agent must infer the distinction from the resource noun alone.

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 an explicit default-and-override rule for committing ('DRY-RUN BY DEFAULT; pass dry_run=false to commit') and an explicit exclusion ('Moving an item to another parent is not supported'), plus a prerequisite (reserve the Classifications set in Teamwork projects). No guidance is given on when to prefer this over the other edit_* siblings.

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 well beyond the annotations: it declares dry-run-by-default, what the preview returns (before/after plus warnings), and precisely what destruction occurs — removing an enum option leaves elements showing <Undefined>, and availability changes have similar consequences, while GUIDs are otherwise preserved. It also names prerequisites (Tapir build with UpdateClassificationItems, Teamwork Properties set reservation), which the destructiveHint annotation cannot convey.

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 highest-value facts: what it edits, that it is dry-run by default, and how to address targets. The example payload is long but earns its place given the untyped `changes` schema. Semicolon-chained clauses make it dense, though not padded.

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, morphologically complex tool this covers prerequisites, safety default, addressing grammar, and consequence of option removal; an output schema exists so return shape needs no explanation. The only omission an agent could trip on is the undocumented `port` 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 coverage is 0% and `changes` is an untyped array of open objects, so the description carries the load — it supplies addressing conventions ('Group/Name' or GUID, 'System/Code' with '/*', enum options by text or GUID when ambiguous) and a full worked example that effectively defines the object shape. `dry_run` semantics are also explained. The `port` parameter is never mentioned anywhere, which is the one remaining 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') and immediately scopes it away from a confusable nearby concept ('not element values'), then enumerates the editable facets (name, description, group, default, availability, enum options). An agent can distinguish it from set_element_data, edit_attributes, and edit_classifications 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 concrete routing: use search_definitions to resolve 'Group/Name', and reserve_elements with object_sets first in a Teamwork project. It also implies the default is a safe preview ('pass dry_run=false to commit'). It stops short of explicitly contrasting against siblings like import_definitions or edit_attributes, so the when-not guidance is implicit 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?

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 declare destructiveHint=true but give no detail; the description supplies the important nuance that the call is dry-run by default, refuses to replace existing files unless overwrite=true, and has a UI side effect (brings the floor plan to the front and leaves it there). It also notes the commit verifies the file and reports its size, and that a versioned dependency 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?

The safety-critical dry-run default is front-loaded and the remaining sentences are terse per-parameter notes with no filler. It is dense and lengthy, but nearly every clause conveys a distinct constraint.

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, 6-parameter export tool with 0% schema coverage, the description covers defaults, side effects, file-collision behavior, required dependency and sequencing. An output schema exists, and the one return behavior that matters (file size returned at commit) is still mentioned.

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

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

With schema description coverage at 0%, the description carries the burden and does well: it specifies path format (absolute, .ifc/.ifczip), translator semantics and default, the full scope enumeration, and the meaning of dry_run and overwrite. Only the port parameter is left undocumented, a minor gap for a connection-level argument.

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 opening clause gives a concrete verb and resource ("Save the project as an IFC file") and immediately positions it relative to the sibling verify_ifc_export_readiness, so an agent can distinguish it from save_project and the readiness check without opening a 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 states the sequencing ("the step after verify_ifc_export_readiness"), the default behavior (dry-run unless dry_run=false), the scope of what a dry run returns, and the negative case ("Never opens or merges IFC"). The overwrite refusal and the prerequisite Tapir 1.6.0 are explicit rather than inferred.

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

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

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

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

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

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

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

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

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

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It clarifies that bcf_path is the file destination, but leaves the optional port parameter completely unexplained; an agent cannot infer what port controls from either the schema or the description.

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

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

The description states a specific verb ('Export'), a precise scope ('every issue in the project'), and a concrete destination ('BCF file at the given path'). This clearly distinguishes it from the sibling import_issues_bcf and other issue-related tools.

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

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

The use case is clear: perform a full-project BCF export to a file path. It does not explicitly name alternatives or state when not to use it, but the scope and purpose are unambiguous enough that an agent can select it appropriately.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the closing 'Reads only' is consistent rather than contradictory. Beyond that, the description discloses genuinely non-obvious behavior: Archicad ignores clashes its own junctions clean up, the volume test only sees closed bodies, collision-excluded building materials are skipped, an empty result is not proof of no overlap, and whole-model checks are slow. That is exactly the kind of caveat an agent cannot get from structured fields.

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 content is dense and nearly every sentence adds operational value, but it is delivered as one long unbroken paragraph mixing calling convention, tolerances, return shape, and Archicad caveats. The return-format sentence is partly redundant with the existing output schema, and breaking the text into grouped statements would make it far easier to parse.

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-required-parameter geometric query tool, the description covers selection, operand grouping, tolerance semantics, performance expectations, and known blind spots. With an output schema already present, nothing an agent needs in order to invoke this correctly and interpret an empty result 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%, so the description carries the full burden and mostly succeeds: it gives the meaning of guids/against_guids/element_types/against_types, the valid Archicad type names with examples, and the units and defaults for volume_tolerance (m3, 0.001) and surface_tolerance (m2, touching faces). Only the connection parameter 'port' is left unexplained, which is a minor gap against an otherwise thorough semantic account.

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 clashes: which elements of one group collide with which elements of another') and immediately defines the two operand groups, so the agent knows exactly what computation is performed. It also differentiates itself from the sibling find_elements by assigning it a distinct role (identifier resolution, not geometric search).

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?

Spells out the group composition rules (guids + element_types vs against_guids + against_types), the self-check fallback when the second group is empty, the prerequisite routing ('for property criteria call find_elements first and pass its GUIDs'), and the specific case where surface_tolerance must be set (open Morph surfaces). This is explicit when-to-use and how-to-configure guidance, not 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?

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 safety is covered; the description adds genuinely new behavior: units (metres, radians, attribute indexes), the 20-element wildcard limit, the presence of 'labels' and 'unreadable' in results, and wildcard vs. exact address semantics. It does not describe error behavior for invalid GUIDs or unknown property addresses.

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 purpose, then organized around the one non-obvious parameter; the parenthetical address forms are dense but each carries distinct information. The long second sentence is heavy but no clause is redundant.

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 and read-only annotations, the description covers the essential extras: units, wildcard limits, and how unreadable kinds surface. The only real gap is the unexplained 'port' parameter and no guidance on failure modes for invalid GUIDs.

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 the load, and it does: 'properties' address grammar is spelled out across five forms with examples and wildcard rules, and include_classifications is explained ('adds every system's item GUID'). 'guids' is self-evident, but 'port' is never mentioned and remains undocumented in both description and 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 opening sentence gives a specific verb and resource ('Read type, layer and requested values of the given elements') and the rest scopes exactly what can be read. It does not name its write-side sibling set_element_data, so the read/write boundary must be inferred from the sibling list rather than stated.

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 context is implied by the address syntax, and search_definitions is cited as the source of property addresses, but the description never says when to prefer this tool over find_elements or get_model_summary, nor that set_element_data is the mutating counterpart. The 20-element cap on wildcard calls is the only explicit operational guideline.

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 well beyond readOnlyHint/destructiveHint by disclosing cost asymmetry between the default and the flag, hard refusal on very large models, a crash risk ('can crash Archicad'), and the semantic caveat that without the Tapir add-on the count is 'NOT a project total'. These are exactly the operational risks an agent needs before calling.

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 core action, then conditions, then caveats; nearly every clause carries information. The final sentence about 'owned_parts' and GDL parts typed as Object is telegraphic and slightly cryptic, but it is not wasted text.

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

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

An output schema exists, yet the description still productively explains the non-obvious output fields ('coverage', 'owned_parts', 'by_type'), plus the add-on dependency that changes the meaning of element_count. The only real hole is the undocumented 'port' 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%, so the description must carry the load. It explains include_layer_story thoroughly (cost, refusal behavior) but never mentions the 'port' parameter, leaving one of two parameters undefined in both schema and prose. Half the parameters are well served, half are not.

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 ('Aggregate element counts') and immediately scopes what it is not: 'Counts only, never element data', which separates it from get_element_data and find_elements. The 'coverage' and 'owned_parts' sentences further pin down exactly what is counted, so an agent can pick it out of a 43-tool family without opening a 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 explicit conditions for the optional flag: default by_type is 'cheap and safe', while include_layer_story=true 'reads a property across every element and is refused on very large models'. That is a real when-to-use/when-not pair. It stops short of naming an alternative tool for the large-model case, so it is not 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 only declare readOnly=false and destructive=false, so the description carries most of the weight and does add real context: highlighting is window-level across all stories, zoom can be suppressed, zero-failure rules clear the highlight, and the add-on prerequisite is disclosed. It stops short of saying whether the highlight persists after the call returns or how it interacts with subsequent API 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?

The core action and scope are front-loaded in the first two clauses, which is good. The remaining sentences are dense with tool-hopping and ambiguous pronoun reference ('show_elements opens the right story or view'), costing more parsing effort than the information justifies.

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 needn't be described, and the add-on requirement is a useful inclusion. Still, one of three parameters is unexplained and the relationship to the sibling show_elements tool is asserted without enough grounding for an agent to act on confidently.

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% across three parameters, so the description must compensate and only partly does: it explains zoom=false and ties rule_id loosely to 'a rule'. The port parameter is never mentioned, and the repeated 'show_elements with guids=[]' phrasing introduces parameter-like syntax for a different tool, which can mislead an agent into thinking guids belongs here.

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?

Opens with a specific verb+resource: highlight elements failing a rule in the Archicad window and zoom to them. Scope ('every story at once') is stated, which separates it from per-story or selection-based siblings. The trailing sentences about show_elements blur the boundary, since they describe another tool's behavior rather than this one's.

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 some operative conditions: zoom=false to leave the view, a rule with no failures removes the highlight, and the Tapir add-on is required. But it never says when to use this instead of show_elements, find_elements, or run_rule, and the show_elements cross-references are asserted without explaining how the two tools relate.

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?

The description adds substantial behavioral context beyond the destructiveHint annotation: dry run by default, sha256 checking, backup behavior on replacement, custom build command loss, macOS password dialog, Windows admin terminal command, restart requirement, and no need for a running Archicad. These details materially help an agent anticipate side effects and platform-specific outcomes.

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 front-loaded with the core action and version, then proceeds through dry-run/write behavior, replacement safety, platform differences, and prerequisites. Despite its density, every sentence earns its place by clarifying a real operational consequence.

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 a destructive mutation with an output schema and three undocumented parameters, the description supplies the missing safety, platform, and prerequisite context. An agent has enough information to decide whether to dry-run, confirm, replace, scope by version, and restart afterward.

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 full parameter burden, and it does: confirm=true writes, archicad_version limits installation to one version, and replace_existing=true is required to replace an existing Tapir while preserving the old copy in backup. All three parameters are explained with consequences.

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

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

The description states a specific verb and resource: install the pinned Tapir add-on version 1.7.3 into Archicad's Add-Ons folder. It clearly distinguishes this operation from general project/model manipulation siblings and makes the target artifact and version explicit.

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 explains the default dry-run behavior, the confirm=true write path, the archicad_version scoping option, and the replace_existing condition with its backup behavior. It does not name alternatives, but there is no obvious sibling installer tool to route against, and the conditions for invocation are 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?

Annotations already flag readOnlyHint=false and destructiveHint=true, and the description goes well beyond that: it discloses that temporary samples are deleted in the same call, that zoom is changed and left changed ('Tapir cannot set the zoom back'), that the Door or Window tool may be left holding the part, the Tapir 1.7.2 GDL restriction causing placed_not_set, and the no-footprint fallback to coordinates. This is unusually rich behavioral disclosure.

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 opening sentence is well front-loaded, but the body is a dense wall of long run-on sentences packed with parenthetical caveats, making it hard to scan. Almost every sentence carries real information, but the packaging could be tightened and structured into clearer units.

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 no output schema, the description usefully explains the reply shape ('samples' left to right, first sample's GDL parameters, warnings, 'next'), plus preconditions like the active, unrotated floor plan and Tapir 1.7.2. It is nearly complete for a complex tool, with the unexplained 'port' parameter as the main 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 carries the full burden. It explains name, kind (object, lamp, door or window) and variants (sets of GDL parameter name/value placed as extra samples), which meaningfully exceeds the bare schema. But the 'port' parameter is never mentioned anywhere, leaving one of four parameters 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 and resource ('learn a library part') and details the full mechanism: placing samples past the right edge, measuring footprints, showing one floor plan image, then deleting the samples and storing the measurement. It also sequences itself against the sibling record_library_part ('next, the fields still to give record_library_part') and distinguishes learning from placement.

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?

'Learn a library part once, before placing it by placement; a learned part is then placed with no samples' gives a clear when-to-use condition versus the placement path. It also adds a precondition for windows ('when a window's capture shows no opening lines... learn the window again, before recording hinge and swing'). It stops short of an explicit when-not-to-use or naming a concrete alternative tool for the placement path.

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 declare readOnlyHint=true and destructiveHint=false, so the description need not re-establish safety. It adds genuinely useful behavior: names-only default output, the richer shapes details=true returns per attribute kind, and the fact that details are paged via limit/offset with next_offset reported while names= bypasses paging.

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 and front-loaded: the type enumeration and default-output mode come first, then details and paging. The mid-sentence '...' elision of attribute kinds is slightly informal but actually saves space without losing meaning.

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 6-parameter read tool with annotations and an output schema, the description covers the default vs details duality and paging semantics thoroughly, so an agent can call it correctly. Only the unmentioned port parameter keeps it from being 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?

With 0% schema description coverage the description carries the burden highly effectively, explaining attribute_type's domain, details, names, limit/offset, and next_offset. The only gap is the port parameter, which is never mentioned in 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?

Opens with a specific verb+resource ('List attributes') and immediately enumerates the valid type domain (Layer, LayerCombination, Line, Fill, etc.), noting plurals work. It also distinguishes itself from the sibling edit_attributes by stating its output uses the same vocabulary edit_attributes accepts.

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?

Clearly explains which mode to use and when: names only by default, details=true to get settings, names= to pick specific attributes, and paging only otherwise. It gives no explicit exclusion against other listing tools like find_elements or get_element_data, but the type-scoped context makes the intended use unambiguous.

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, and the description adds meaningful behavior: it reads only the local records file, needs no Archicad, reports missing fields, names unrecorded requested parts, and returns the records file path. This is substantial extra 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 front-loaded with the core list operation and then layers in filtering, returned fields, missing/not_recorded semantics, and local-file behavior. The sentences are dense but purposeful, with no obvious 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 low-complexity, single-optional-parameter read tool with an output schema and read-only annotations, the description provides enough context to invoke it correctly. It also explains key return semantics and the local-file/no-Archicad constraint.

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?

Although schema description coverage is 0%, the single optional parameter is explained in the description: names limits results to only those parts, while omission returns all records. The schema supplies the array-of-strings type and null default, and the description compensates well for the semantic 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 gives a specific verb and resource: it lists learned library part records. It also clarifies the optional names filtering and the returned data categories. It does not explicitly differentiate itself from sibling tools such as learn_library_part or record_library_part, which keeps it from a 5.

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

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

The description explains that it can list all records or only those named in names, which implies when to use the parameter. However, it does not explicitly state when to choose this tool over siblings like learn_library_part or record_library_part, nor does it give exclusions or alternatives.

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?

Far exceeds what destructiveHint=true conveys: it discloses the dry-run preview payload (current vs new value per field, skipped elements with reasons and warnings), that locked/hidden/other-view/Teamwork-unreserved elements are skipped and never unlocked, that leaves are written after commit with a 'placed_not_set' marker, and that commits read back into modified/failed/not_applied. This is exactly the behavioral context 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-loading is good — 'Change existing elements' and the DRY-RUN DEFAULT warning come first. But the body is a single dense block cramming field naming, placement/sketch workflow, skip rules, and read-back semantics together; splitting or trimming the placement narrative would improve scanability without losing 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?

For a destructive, multi-type mutation tool with an output schema, it covers what an agent needs: default-safe behavior, per-type field sourcing, unit conventions, refusal handling, placement workflow, and result interpretation. Only the unexplained port parameter and untested type-coverage boundaries keep it from being flawless, but nothing essential to calling it correctly is absent.

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 the load — and it does for the two consequential parameters: changes is defined as {"guid", ...fields} with units (metres, radians, mm), accepted field families, and partial-value completion from current state; dry_run is fully specified including its return shape. The port parameter is never mentioned, leaving 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?

Opens with a specific verb+resource ('Change existing elements') and immediately distinguishes itself from create/move/delete by describing in-place field modification on an identified element. It also names the concrete mechanism (guid + per-type fields, set_element_data fallback for older Tapir) that separates it from sibling write 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?

Strong workflow guidance: dry-run is the default, dry_run=false commits, describe_api_command ModifyWalls is named for discovering per-type fields, and it prescribes a look-then-correct loop with capture_window after placements. What is missing is explicit routing against siblings like move_elements or set_element_data ('use X instead when...').

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

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

Beyond the destructiveHint annotation, the description discloses the confirm gate, active-window database scope, refusal categories (hidden/locked layers, Teamwork reservation, hotlinked modules, etc.), and the shape of per-element results. This is unusually rich behavioral context 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?

The description is dense but front-loaded: the core action, confirmation gate, scoping behavior, and return shape arrive in order. It is appropriately sized for a destructive operation, though the refusal list is packed into one long clause.

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 mutation with an output schema, the description covers the confirmation requirement, the active-window scope, refusal reasons, and the return structure. The only notable omission is the unexplained 'port' parameter, but otherwise an agent has enough to call 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?

With 0% schema description coverage, the description must carry parameter meaning. It explains the vector format and units and the confirm gate, and implies guids through refusal/return wording, but it never explains the 'port' parameter and does not fully describe the GUID list semantics.

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

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

The description states a specific verb and resource ('Move elements') and specifies the mechanism ('by a vector {x,y,z} in meters'), which clearly distinguishes it from broader siblings like modify_elements. An agent can identify the operation 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 clearly gives the critical precondition ('Refuses without confirm=true') and explains Archicad's active-window scoping, including which elements will not be sent. It does not explicitly compare against alternatives such as modify_elements, but the operational context 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?

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?

Goes well beyond the annotations: it discloses that it writes only the MCP's own learned-parts file, never the model, needs no Archicad, is atomic on refusal ('One refused value saves nothing'), and that forget removes a record that can be re-learned. It also explains the merge semantics of combos/leaf_states versus replace-on-write for other fields.

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 action and the two data families, and every clause carries real information. It is dense, semicolon-heavy prose that takes careful reading, which slightly hurts scannability.

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?

Even though an output schema exists, it still states the return value including 'missing', the list of fields still needed before placement. Combined with atomicity, merge rules, and the wall-facing head convention, an agent has everything needed to call 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?

With 0% schema coverage, the description carries the full burden and mostly discharges it: allowed head values and axis meaning, height in metres, one_sided as boolean, the four combo flag-pair keys with [hinge, swing] semantics, leaves as an integer >= 1, and leaf_states as name-to-GDL-values. Only 'name' is left implicit, which is self-evident.

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?

Names a specific verb (record) and resource (the part's stored record) and explicitly frames the input as the judgement produced from learn_library_part's image, separating it from the sibling that produces that image. The two families of data it accepts (objects/lamps vs doors/windows) are spelled out.

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?

States the prerequisite ('The part must have been learned first'), the forget=true mode and that it 'takes no other field', and explicitly tells the agent to ask the user when the image is ambiguous. It does not contrast with list_library_part_records, but the usage context is otherwise unambiguous.

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=false; the description goes well beyond by disclosing the dry-run default, the exact report fields in each mode, that unsent changes survive a release, and that releasing an object_set flushes that set's changes to the server first. That is precisely the mutation-risk context an agent needs and cannot get from the structured fields.

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 core action, then the confirm gating, then caveats — a sensible ordering, and every sentence contributes. The parenthetical asides and the run-on final sentence make it slightly denser than necessary.

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 names the return fields in both modes, which is more than sufficient. The gaps are the unexplained port parameter and the unresolved guids/object_sets relationship for a 4-parameter, all-optional tool.

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

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

Schema coverage is 0%, so the description must carry the load; it explains confirm's dual semantics and the object_sets naming contract inherited from reserve_elements, but never explicitly mentions the guids parameter or clarifies whether guids and object_sets can be combined, and the port parameter is entirely unaddressed.

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: "Release elements, and non-element object sets, from your Teamwork workspace (Tapir)." It also signals the conceptual sibling by referencing reserve_elements for the object_sets naming convention, though it never explicitly contrasts with delete_elements, a plausible confusion for an agent.

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 two-phase workflow is spelled out with concrete outcome states (would_release/not_mine/not_found vs released/still_mine), which tells the agent exactly how to probe before committing. It stops short of naming an alternative tool or stating exclusion cases such as when deletion rather than release is appropriate.

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 well beyond the annotations: it discloses the confirm-gate contract, the exact outcome keys per mode, version-dependent behaviour (held_by_others readable on Tapir 1.7.3, attempt-only on older), Tapir 1.7.1 requirement for sets, and the real-world effect that a reservation is visible to teammates and blocks their edits until released.

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 core action and the CONFIRM-GATED contract are front-loaded in the first two clauses, and the long middle sentence is dense but information-bearing. It is wordy (multiple semicolon-chained asides about Tapir versions) and could be tightened without losing meaning.

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 enumerates return keys usefully, and it covers the version and set-entry semantics an agent needs to interpret results. The only meaningful gap given the tool's complexity is the unmentioned port parameter and the lack of any note about Teamwork/server connectivity requirements.

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 burden and mostly does: confirm is explained in detail, object_sets is explained with accepted value families and per-entry fields, and guids is implied by 'elements'. The port parameter is never mentioned, leaving one of four parameters undocumented anywhere.

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 ('Reserve elements, and non-element object sets, in a Teamwork project') and explains the intent ('so you can edit them'). The reservation semantics make it clearly distinct from create_elements, modify_elements and release_elements among the siblings.

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 explicit when-to-use guidance for its two modes: without confirm=true it is a safe dry run, with confirm=true it actually reserves. It does not name the natural alternative (release_elements) or state prerequisites such as needing an active Teamwork connection, so it stops short of full routing 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 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 already declare readOnlyHint=false and destructiveHint=true, and the description adds real context beyond them: the confirm-gated dry-run behavior, Teamwork semantics (saves local copy, never sends), refusal reporting for unsupported projects, and the file_updated signal. Nothing here contradicts the destructive/read-write 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?

Front-loaded with verb, resource, and the CONFIRM-GATED warning. The long enumeration of crash-prone siblings is dense but earns its space by giving concrete preconditions; it is close to the limit of readability but not padded.

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 flags file_updated meaningfully. Combined with the failure modes and Teamwork caveat, an agent has everything needed 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 coverage is 0%, so the description must carry the param burden; it does for the critical one, explaining that without confirm=true the tool only reports what it would save. The port parameter is left unexplained in both schema and description, which is the remaining 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 plus scope: saves the open project to its own file, equivalent to File > Save. It explicitly distinguishes itself from Save As and from the recovery-oriented sibling operations by naming 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?

Gives an explicit when-to-use rule (call before the listed crash-prone reads/writes) and enumerates the exact sibling tools that qualify. It also states the case where the tool will not work (never-saved or older-version projects need File > Save As in Archicad).

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.