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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false. The description adds real value beyond that: it discloses that all additions collapse into 'one undo step' and that the call batches multiple comments/issues, which is genuinely useful behavior 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?

A single sentence, front-loaded with the action and scoping, with the output contract folded in compactly. Nothing is wasted, though the trailing output shape makes it slightly dense.

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 correctly inlines the return shape and ordering ('in input order'), and annotations cover the safety hints. The only real gap is the undocumented undoName parameter, which is minor against an otherwise complete picture.

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 only 50%, and the description names no parameters at all. The comments array fields are documented in the schema, but undoName (maxLength 255, no description) is left entirely undefined in both places, so the description fails to compensate for the coverage 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+resource ('Adds comments to issues') and immediately distinguishes itself from the read-side sibling get_issue_comments and the create_issue sibling. It also conveys batch scope ('several comments / issues per call'), so an agent knows this is the write path for commenting.

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 intent is implied clearly by the name and the batch note, but it never says when to prefer this over get_issue_comments or create_issue, nor any prerequisite (e.g. issue must exist). No explicit alternatives or exclusions are named.

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 past the annotations by declaring 'NOT undoable' (a concrete reversibility statement), stating that already-loaded paths are reported rather than erroring, and naming the return payload (per-path results plus the new library list). This is consistent with destructiveHint=true and idempotentHint=true and adds real decision-relevant context.

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

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

Three tight sentences with no filler, and the critical constraint ('NOT undoable') is placed early. Dense but every clause carries information an agent needs.

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 compensates by summarizing the return shape, and it covers path format, undoability, and repeat-call behavior for a destructive single-parameter mutation. Only explicit sibling differentiation is missing.

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

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

Schema coverage is 100% (baseline 3), and the description adds meaning the schema lacks: '~/' expansion, that values are Mac-local absolute paths, and that .lcf library containers are also acceptable. That is genuine added semantics over the schema's single 'paths' 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?

Specific verb+resource ('Adds local libraries to the project and loads them') with the accepted input kinds spelled out (absolute folder paths or .lcf containers). It clearly distinguishes the operation from a plain read, but never names or contrasts the nearby siblings remove_libraries / reload_libraries / get_libraries, so the agent must infer which of the four library tools to pick.

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

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

Usage is implied rather than stated: the path-format rules and the 'alreadyLoaded' behavior tell the agent it is safe to re-run, but there is no explicit when-to-use-this-instead-of-X guidance despite three sibling library tools. Adequate but leaves the agent to infer the routing.

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

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

Annotations declare destructiveHint=true, idempotentHint=true, readOnlyHint=false; the description is consistent and adds real context beyond them: what survives (geometry, position, story) when injecting into Elements, and the full output shape per target. It does not discuss permissions/locks or failure modes beyond the per-element error shape, so it is strong but not exhaustive.

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

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

Front-loads the core action, then adds target semantics and output in compact, information-dense sentences with zero filler. It is somewhat long and dash-heavy for a two-mode tool, but every clause carries distinct operational 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?

With no output schema, the description compensates by enumerating the return fields per target (favorite, type, variation, target, applied, results, warnings), and it fully covers both modes. The remaining gap is the three boolean apply* toggles and undoName, which the schema documents but the description never contextualizes.

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 already 86%, so the baseline is 3, but the description genuinely extends the target parameter's meaning by spelling out the downstream consequences of each enum value (future elements inherit settings vs existing same-type elements are modified in place). undoName and the apply* flags are left entirely to the schema, which is acceptable at this coverage.

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

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

States a specific verb+resource ('Applies a favorite') and immediately disambiguates the two operating modes (Defaults vs Elements). An agent can distinguish it from create_favorite, delete_favorite, rename_favorite, and set_tool_defaults without opening any 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?

Explains the two targets and their effect, including the 'like double-clicking it in the Favorites palette' analogy for Defaults and the geometry/position/story preservation for Elements, which tells the agent which mode fits which situation. It lacks an explicit pointer to sibling tools (e.g., get_favorites to discover names, or create_* vs set_* alternatives), so it stops just 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 declare destructive=true, idempotent=true, readOnly=false; the description corroborates by explaining that applying a combination rewrites the state of ALL layers, which is the source of the destructive/wide-blast-radius behavior. It also documents the return shape, adding value 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?

Three tight sentences, front-loaded with the action and effect, followed by the discovery pointer and return shape. Every sentence carries information; nothing is 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?

With no output schema, the description usefully names the return fields (ok, layerCombination, activeLayerCombination), and annotations plus a 100%-covered schema handle safety and input. Only an explicit when-vs-alternatives statement is missing.

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

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

Schema coverage is 100% and the schema already documents the accepted forms (name, index, {index}, {name}, {guid}). The description adds only the discovery hint, which sits outside the parameter itself, so baseline 3 is appropriate.

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

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

Specific verb (makes active) plus resource (saved layer combination) and the concrete effect (sets visibility/lock/wireframe of all layers). This distinguishes it from the many layer/state siblings such as set_layer_states and create_layer_combinations.

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 a discovery pointer (list combinations with get_attributes {type: 'LayerCombination'}), which helps the agent find valid values. However, it never states when to prefer this over set_layer_states or other layer-state tools, so usage is only implied.

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 readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds real context beyond that: it explains the distinction between the Claude Connector add-on ('full create/modify power') and the Tapir add-on, which tells the agent what capabilities are available after the check.

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 sentence enumerating the return contents, followed by a single short directive sentence. Front-loaded with the core purpose and no wasted words.

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

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

With no output schema, the description correctly takes on the burden of describing what is returned (instances, active instance, add-on availability). It is nearly complete for a diagnostic tool, though it doesn't indicate behavior when no instance is running or the error/empty-result shape.

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 takes zero parameters, so there are no parameter semantics to explain; baseline 4 applies. The description appropriately uses its space to describe outputs instead.

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 ('checks the connection') and enumerates exactly what it reports: running Archicad instances with port/version/build/language, which is active, and add-on availability. This is clearly distinguishable from siblings like select_archicad_instance or get_connector_guide.

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?

'Call this first if anything fails' gives an explicit, actionable trigger condition for the tool. It does not name alternative diagnostic tools or state when NOT to call it, but the usage context is clear.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds that the operation is 'one undo step' and discloses the response shape including a missing?: list of non-existent element GUIDs. That is real context beyond the annotations, though permission/auth constraints and what 'destructive' means here go unstated.

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 dense but useful clause-by-clause detail on each type and the return payload. Every sentence earns its place; slightly dense in the middle 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?

With no output schema, the description appropriately spells out the return object and the meaning of each type. The only gaps are undoName semantics and any mention of failure/authorization behavior for a destructive operation.

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

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

Schema coverage is 80%, but the description adds non-obvious semantics: modificationPairs may be omitted (Modification implied), and with plain elements Archicad creates a modified copy of each. Only undoName is left unexplained, which is minor.

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 ('Attaches elements to an issue') and distinguishes itself from likely siblings (detach_elements_from_issue, get_issue_elements) by describing the four attachment semantics. An agent can tell what it does without opening the schema.

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

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

Explains when each type value applies (Highlight points, Creation/Deletion propose, Modification pairs or copies), which is genuine usage guidance for choosing behavior. It does not name sibling tools or state exclusions, so it stops short of a 5.

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

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

Annotations set readOnlyHint=false, and the description explains the side effects that justify it: it switches to the 3D window, width/height temporarily resize the 3D window, and images are downscaled to maxSize (default 1600). These are real behavioral facts beyond the annotations. It omits the return payload shape, but the image return is stated.

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 purpose, then preparation order, then caveats and examples. Dense but each clause earns its place; the parenthetical cross-references are compact. Slightly long 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?

For an 11-parameter tool with nested objects and no output schema, the description covers capture target, preparation ordering, defaults (maxSize, format, cropToWindow implied), and the zoom-first caveat for 2D. The absence of an output schema is not a gap since it states the return is an image. Minor omission: no explicit statement about error/permission behavior.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value the schema cannot: it names the cross-tool field sets ('same fields as open_view', 'same fields as set_3d_view', 'same fields as zoom') and supplies worked examples. The ordering constraint among the nested objects is also semantic information not present in the schema.

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

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

States a specific verb+resource ('saves the ACTIVE Archicad window ... as a picture and returns it as an image') and enumerates the window types covered, which cleanly separates it from siblings like render_view, export_3d_model, and export_pdf. An agent can tell what it produces (an image of the current window) without opening the schema.

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

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

Gives clear operational context: the optional preparation order (goToView -> view -> threeD -> zoom) and the condition that 2D windows capture at the current zoom, so use zoom {mode:'fit'} first. It does not explicitly exclude alternatives (e.g. render_view for photorealistic output) or state when-not-to-use, which keeps it below a 5.

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

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

Annotations declare destructiveHint=true, idempotentHint=true, openWorldHint=false. Description adds rich behavioral context: single undo step, position/orientation preserved, type constraint, default-parameter behavior (keepParameters/keepSize), parameter scripts run like the settings dialog, and the return shape. This goes well beyond what annotations cover.

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, front-loaded with the verb and scope. It is information-dense and every clause carries meaning, though the middle section on keepParameters/keepSize/params reads a bit compressed and could be structured as a short list. Not bloated, but not maximally scannable.

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 mutation tool with rich schema and annotations, the description covers behavior, defaults, constraints, and return shape, so an agent has everything needed to call it correctly. No output schema exists, and the description does include the return format, which is a strong addition.

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 80%, but the description explains semantics of the key behavioral parameters (keepParameters default true, keepSize default true for doors/windows/skylights, extra params applied afterwards) and the top-level vs per-element libraryPart precedence. Adds real meaning beyond 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?

Specific verb ('Swaps'), specific resource ('library part of placed objects...'), enum of affected element types, and examples ('replace a chair model, change a door type'). Clearly distinguishable from siblings like modify_elements or set_gdl_parameters.

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?

Description implies when to use it: when swapping library parts across objects/doors/windows/etc. It notes the type-matching constraint (new part must be same type), which is a usage prerequisite, and contrasts with set_gdl_parameters via its param semantics. No explicit 'use X instead when Y', but context is clear.

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

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

Annotations declare a safe non-destructive, non-idempotent write; the description adds beyond that by specifying the output ({viewId}) and that the copy inherits the current view settings. It does not warn that repeated calls produce duplicate View Map items, which is the one behavioral trait an agent would want given idempotentHint=false.

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 source/destination mapping; the output clause is clearly separated. The parenthetical enumeration of viewpoint types is somewhat long but serves to define the resource, so it earns most of its space.

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 mutation tool with no output schema, the description supplies the return shape ({viewId}) and the follow-on placement workflow, and the schema covers the params. Only the duplicate-creation behavior on repeat invocation is left unstated, a minor gap.

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

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

Schema description coverage is 100% – both 'item' and 'parent' are documented in the schema, including the hint to obtain ids via get_navigator_tree. The description adds no parameter-level detail (e.g., default parent behavior) beyond that, so baseline 3 applies.

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 precise verb ('Saves ... as a new view') and both resources involved: the Project Map item source and the View Map destination. The analogy to 'Clone a view' in the Navigator and the enumerated viewpoint types (story, section, elevation, 3D view...) make it unmistakable which sibling operations it is not, e.g. create_view_map_folder or create_layout.

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

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

Explains the effect and what can be done afterward ('The new view can then be placed on layouts'), which gives the agent a clear context for choosing this over get_view_settings/set_view_settings. It does not name an explicit alternative or state when NOT to use it, so it falls short of a 5.

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

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

Annotations already flag destructiveHint=true, but the description adds the critical non-obvious consequence: the JSON API only listens while a project is open, so after this call NO tool works until a human reopens a project. That is the single most important behavioral fact for an agent and it is not derivable from annotations or schema.

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

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

Three sentences, front-loaded with the action, then the irreversibility warning, then the routing and prerequisites. No filler; each sentence carries distinct 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, non-idempotent mutation with no output schema, the description covers the safety profile (annotations), the hard consequence of calling it, the alternative tool, and the required parameters. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so all three parameters are already fully documented in the schema, including the 'exactly one of saveFirst/discardChanges' constraint and the untitled-project caveat. The description only restates the requirement, adding no new parameter meaning. Baseline 3 applies.

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 ('Closes the current project') and immediately differentiates itself from the sibling switch-project tools (open_project/new_project) and from quit_archicad by naming them. 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?

Explicitly routes the agent: 'Prefer open_project/new_project to switch projects', which is exactly the when-not-to-use guidance. It also states the precondition (confirm: true plus saveFirst or discardChanges), so the agent knows the invocation requirements before calling.

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 the safety profile (readOnly=false, destructive=false, idempotent=false). The description adds substantial context beyond that: originals are preserved, copies inherit settings/story/layer/properties, host-dependent elements (windows/doors, openings, group members, associative dimensions) are created along with the copies, and internal group handling suppresses group membership by default. This is 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?

Purpose and the originals-stay constraint are front-loaded, then behavior, then the sibling reference. The long return-value enumeration is verbose, but since there is no output schema it is doing necessary work 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 complex mutation tool with no output schema, the description covers input semantics (vector, count), side effects (dependent/associative elements created), group handling, and fully enumerates the return shape including createdGroups, additionalCreated, subElementsCreated and warnings. 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?

Schema coverage is 100%, so the baseline is 3. The description goes further with a concrete worked example ('10 columns every 6 m: vector {x: 6, y: 0}, count 10') that makes the count-times-vector semantics intuitive, and clarifies that copies retain all original properties. It adds real meaning over the schema text, though much of the count/vector behavior is already documented in the schema.

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

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

States a specific verb and resource ('Duplicates elements of ANY type') and immediately anchors it to the GUI operation 'Edit > Move > Drag a Copy' with the key constraint that 'the originals stay'. It also distinguishes itself from the sibling copy_elements_to_stories, so an agent can pick the right copy tool without opening schemas.

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

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

It explicitly routes cross-story duplication to copy_elements_to_stories and explains the count>1 array pattern with a worked example, giving clear context for when this tool applies. It stops short of stating when NOT to use it (e.g. vs move_elements or create_elements), so it's clear but not exhaustive.

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 by explaining the relative-elevation semantics with a concrete worked example, the top-linked wall/column behavior, host/opening travel, and the group handling (Suspend Groups toggled and restored). It also documents the return structure, which is significant given there is no output schema.

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 relative-elevation semantics and packs supporting detail into tight parentheticals. The final return-shape sentence is dense but justified because no output schema exists.

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

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

For a mutation tool with no output schema, the description covers the semantics, edge cases (groups, hosted elements), the dependency on get_stories, and the response shape. Nothing an agent needs to call it correctly appears to be 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 100%, so the schema already documents all three parameters, including the accepted story formats and the includeGroupMembers default. The description only adds a pointer to get_stories, so the baseline 3 is appropriate.

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

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

States a specific verb and resource (duplicates elements onto other stories) with the defining constraint of keeping elevation relative to the home story, which cleanly separates it from copy_elements and move_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?

Gives concrete selection guidance (copy walls/roofs/slabs rather than their windows/doors; hosted openings travel with their host) and points to get_stories for resolving story references. It lacks an explicit statement of when to prefer this over same-story copy_elements, but the context is clear enough to route correctly.

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 non-read-only, non-destructive, non-idempotent creation. The description adds useful behavioral context beyond annotations: it is a single undo step, elements are linked to end points when possible and verified, and the return shape is documented.

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 with the core action, then covers input modes, arc placement, and return value. Every clause carries practical information for invoking or interpreting 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?

For a complex creation tool with no output schema, the description covers the essential creation modes, undo behavior, linking behavior, and return fields. Remaining formatting details (pens, fonts, markers, story) are documented in the schema, so the description is sufficiently complete without repeating 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?

The schema documents many nested properties, but the description adds relational meaning that the schema alone does not: arcPoint/radius interaction, the arc being centered on the lines' intersection, default placement between far ends, and associative linking behavior.

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: 'Dimensions the angle between two non-parallel lines'. It immediately distinguishes this from linear, level, or radial dimension tools by specifying the angle measurement and the two supported input modes.

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

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

Explains the two valid usage modes (static line1/line2 or two straight elements) and notes defaults such as arc placement. It does not explicitly name sibling tools or say when to choose those alternatives, but the context is clear enough for an agent to know when this tool applies.

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 idempotentHint=false, so a mutation is expected. The description nonetheless adds real value: the CCW storage quirk (clockwise arcs come back with begin/end swapped), the active-window database targeting with storyIndex default, and the per-item failure semantics ('one failing item does not stop the others') with the [{guid,type}|{error}] return shape. This is richer than the annotations alone, but it is one of many traits and does not describe auth or limits, so a 3 reflects solid-but-not-exhaustive 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?

Dense but front-loaded with the purpose, then forms, then placement, then return/error behavior, then follow-up tools. Every sentence carries information; the only cost is high density that a hurried reader must parse carefully.

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 compensates by specifying the return shape and partial-failure behavior. Combined with placement rules, defaults, the elliptical-arc options, and the modify/get follow-ups, nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds compositional meaning the schema cannot: it explains how the parameters combine into three distinct arc forms, the degrees/CCW convention, and the sign convention for arcAngle (+ = CCW). That goes beyond the per-field definitions.

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 ('Draws 2D circular or elliptical arcs') and immediately distinguishes itself by naming the sibling for full circles (create_circles) and the related line/circle creation tools. An agent can tell at a glance this is the arc-creation tool, not a line or circle tool.

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

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

Explicitly lays out three alternative ways to define an arc (A: center+radius+angles, B: begin+end+arcAngle, C: begin+through+end) and routes to create_circles for full circles, modify_elements for later edits, and get_element_details for reads. It also states the placement constraint (active window; a 3D window cannot hold 2D elements), which is a genuine when-this-works condition.

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 write, non-destructive, non-idempotent. The description adds genuinely useful behavioral detail: missing parent folders are auto-created, and the per-folder result format (guid/ok vs error) is shown despite no output schema. It does not state what happens on duplicate existing folders, but the disclosed cascade and output shape exceed the annotation baseline.

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

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

Three sentences, each earning its place: purpose plus cascade behavior first, output shape second, next-step sibling third. Front-loaded and free of waste.

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 covering safety and a fully described input schema, the description supplies the missing output shape and cascade behavior needed to call it correctly. Minor gaps remain (e.g., behavior on existing folders, 200-item limit), but it is largely complete for a two-parameter creation 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 description coverage is 100% and the schema itself explains path formats (array, slash-string, root), the {guid} alternative, and the attributeType enum in detail. The description only repeats 'by full path' and an example already present in the schema, adding no new semantics beyond the structured fields.

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 ('Creates attribute folders by full path') and clarifies scope with the cascade behavior. It also distinguishes itself from the sibling move_attributes_to_folder by directing attribute movement to that tool, so an agent can tell what this tool is and is not 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?

Implies usage (creating folders, then moving attributes in with a named sibling) but provides no explicit when-to-use vs alternatives, no prerequisites, and no guidance on checking existing folders via get_attribute_folders first. The follow-up suggestion is helpful but not a full usage 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?

Adds substantial context beyond the annotations: it is a single undo step, unspecified settings inherit Beam tool defaults, the return format is [{guid, type} | {error}] in input order, and holes replace ALL existing holes. These are behavioral traits the annotations (readOnly=false, destructive=false, idempotent=false) do not 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-loads what the tool creates, then units, then the 'level' semantics with an example, then a representative payload, then the return shape. It is dense and mostly earns its length, though the geometry enumeration and example make it longer than strictly minimal.

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 very large input schema, the description covers the essentials an agent needs: scope, units, defaults source, level semantics with example, chaining, undo behavior, and return format. No output schema exists, and the description supplies the return contract, so nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: units summary (meters/degrees), the semantic of 'level' with a worked example (story height 3 m, level 2.8 = beam under slab), and the chaining convention. It does not attempt to explain the many section/surface fields, which the schema already documents well.

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 (Creates) and resource (beams) and enumerates the geometry variants supported (straight, curved, slanted, tapered, complex-profile, multi-segment). This clearly distinguishes it from siblings like modify_beams, create_columns, and create_elements.

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

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

Gives concrete usage context: coordinates in meters, angles in degrees, default story, chaining rule ('Chain beams end-to-start so Archicad connects them'), and that unspecified settings come from Beam tool defaults. It does not explicitly contrast create vs modify (modify_beams) or name when not to use it, so it stops short of a 5.

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

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

Goes well beyond the annotations by disclosing default inheritance behavior ('Unspecified settings are copied from basedOn or ... the first building material of the project'), undo semantics ('Runs in one undo step'), partial-failure handling ('one failing item does not stop the others'), the exact return shape, and localization constraints. This is rich behavioral context for a non-readOnly, non-idempotent 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 and every sentence carries useful information: purpose, defaults, undo behavior, return format, and localization advice. It could be slightly easier to parse if broken into shorter lines, but there is essentially no 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?

For a complex creation tool with no output schema, the description covers the essential behavior an agent needs: what will happen to unspecified fields, undo grouping, partial failure semantics, return structure, and a key prerequisite for name lookups. Annotations and the rich input schema handle the remaining safety and field-level 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?

The schema already documents many nested fields thoroughly, but the description adds genuine meaning: it explains the fallback behavior for unspecified settings, recommends which fields to provide for a meaningful material, and clarifies the role of basedOn. It does not cover every parameter or the batch array limits, but it adds real value beyond the structured 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?

States a specific verb (Creates) and resource (building materials), and explains the domain concept ('material of elements and composite skins: cut fill + pens, surface, intersection priority, physical properties'). This clearly distinguishes it from sibling attribute-creation tools like create_surfaces, create_fills, and create_composites.

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 workflow guidance: 'look existing attributes up with get_attributes first,' and advises giving at least cutFill, surface and uiPriority for a meaningful material. It does not explicitly name alternatives or when-not-to-use conditions, which keeps it from 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?

With readOnlyHint=false, destructiveHint=false, and idempotentHint=false already declared, the description still adds real behavior: placement is bound to the active window type, 3D windows reject 2D elements, results are returned per-item in input order, and one failing item does not abort the batch. It does not state permission/undo implications, but the partial-failure and window-constraint disclosures go meaningfully 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?

Front-loads what the tool draws, then the style fields, then the storage/return contract, so the most decision-relevant facts come first. It is dense and somewhat long, but nearly every clause (window constraint, default story, batch error semantics, follow-up tools) carries 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?

There is no output schema, yet the description spells out the return shape ([{guid, type} | {error}] in input order) and partial-failure semantics. Combined with the window/story placement rules and pointers to modify_elements and get_element_details, an agent has everything needed to call this 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 100%, so units (m, mm, degrees), defaults, and enumerated style fields such as pen, colorOverridePen, lineType, lineWeight, category, and zoneBoundary are already documented in the schema. The description restates a subset of these fields and adds units but no syntax or semantics the schema lacks, matching the baseline 3.

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 (draws full 2D circles / ellipses) and immediately disambiguates the geometry via the required parameters (center + radius, minorRadius/axisAngle for ellipses). It is easily separable from siblings like create_arcs, create_polylines, and create_elements without opening any 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 usage context: elements land in the ACTIVE window's database, the floor plan uses storyIndex (default current story), and a 3D window cannot hold 2D elements. It also routes the agent onward to modify_elements and get_element_details. It stops short of explicit sibling alternatives (e.g. when to prefer create_arcs), so it is clear context rather than full when/when-not routing.

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

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

Beyond the annotations, it discloses that all items are added in one undo step, that item IDs must be unique within the system, and it gives the exact return shape including per-item error handling and created/failed counts. For a write tool with no output schema, this is substantial behavioral context.

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

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

The description is two dense sentences, front-loading the action and then constraints and return shape. Every clause 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?

For a nested write tool with no output schema, the description covers purpose, nesting, uniqueness, undo behavior, and return format. It could be slightly more explicit about partial success semantics, but overall it is quite 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 75%, and the description mostly restates what the schema already documents: the nested item shape, optional parent, and before/append insertion. It adds little new parameter meaning beyond what is already in the field descriptions.

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

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

The description states a specific verb ('Adds') and resource ('classification items') with the scope 'to an existing classification system'. This implicitly distinguishes it from create_classification_system and from modify/delete item tools, but it never names a sibling alternative, 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?

Usage is implied by 'existing classification system' and the detailed insertion behavior, but the description never states when to use this tool instead of modify_classification_items, import_classifications_xml, or create_classification_system. No exclusions or alternative routing are provided.

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 by disclosing atomicity ('in one undo step'), the uniqueness constraint on name+editionVersion, and partial-success semantics via the return shape (items with either {guid,...} or {id, error}, plus created/failed counts). This is meaningful 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?

Front-loaded with the core action and scope, then layers constraints, item shapes, workflow, and return shape. Dense but each sentence carries distinct information; only minor tightening would help.

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 an 8-parameter, nested-tree mutation tool with no output schema, the description covers the action, constraints, input shapes, downstream workflow, and return structure. Coverage is strong, with only edge behavior (e.g., failure modes when reuseExisting is false and the system exists) left implicit.

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 high (88%), so the schema carries most parameter meaning. The description still adds value by explaining the two accepted input shapes for items — nested children vs. flat with parent referencing an earlier item's id — which complements rather than repeats the schema.

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

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

States a specific verb and resource ('Creates a classification system') and immediately scopes it to optionally include the full item tree, plus an analogy to the Classification Manager's 'New' for humans. This distinguishes it from siblings like create_classification_items and modify_classification_system.

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 workflow guidance ('Then classify elements with the official classification tools and use the items in property availability') and a uniqueness constraint ('name + editionVersion must be unique'). It does not explicitly name the alternative sibling to use when only adding items to an existing system, though reuseExisting is hinted via schema.

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 this is a non-readOnly, non-idempotent, non-destructive write. The description adds valuable beyond-annotation context: it is a single undo step, unspecified settings inherit from the Column tool defaults (which are often top-linked), and it returns [{guid, type} | {error}] in input order. It doesn't discuss failure modes like batch partial failure in depth.

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?

Content is dense but front-loaded: purpose first, then coordinate/story defaults, then the height caveat, then the example, then the return contract. Every sentence carries information, though the enumeration of column types and the example make it slightly longer than strictly 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?

With no output schema, the description correctly supplies the return shape ([{guid, type} | {error}] in input order) and points to get_element_details for reading back segments, cuts and elevations. Combined with a working example, an agent has what it needs to call this 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 100%, so the baseline is 3; the description still earns more by explaining the height/topLinkedStory/topOffset interaction and giving a concrete typical payload, which disambiguates how the params combine. It does not document the full range of section/surface fields, but the schema already does that.

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 states a specific verb and resource ('Creates columns'), then enumerates the variations it supports (rectangular, circular, complex-profile, tapered, slanted, multi-segment). This clearly distinguishes it from sibling modify_columns and the other create_* element 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 gives concrete guidance on scoping (coordinates in meters, angles in degrees, default current story) and a critical usage tip about supplying 'height' or 'topLinkedStory' so the height is predictable, plus a 'typical' object example. It does not explicitly name modify_columns as the alternative when editing existing columns, so it stops short of a 5.

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

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

Annotations only state read/write and idempotency flags; the description goes further by disclosing that it runs in one undo step, that failures are per-item and do not abort remaining items, that basedOn copies an existing composite, and that names are localized (Russian Archicad). This is exactly the kind of behavior the annotations 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 purpose, then the key semantic rule (skin ordering) and a worked example, which is efficient for a complex nested schema. The get_attributes reminder appears twice and the example is verbose, costing some tightness.

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 tool with a deeply nested item schema and no output schema, the description closes the gaps that matter: it documents the return shape ({results: [...]} in input order with created/existed/error variants), partial-failure behavior, and the undo grouping.

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 only 50%, but the description compensates substantively: skins are ordered outside→inside, total thickness is the sum, a concrete worked example shows thickness/buildingMaterial/core/finish usage, and basedOn semantics are clarified. It omits usage, folder and skinLines, which the schema does document.

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 ('Creates composite (multi-skin) structures for walls, slabs, roofs and shells'), immediately distinguishing it from sibling attribute creators like create_building_materials and create_surfaces by naming the element types involved.

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 routes the agent: fetch material names with get_attributes type BuildingMaterial, then attach the composite via the 'composite' field of create_walls / create_slabs / create_roofs, and look existing attributes up first for localized names. Prerequisites and downstream consumers are named, not implied.

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 readOnly=false/destructive=false/idempotent=false, so the burden is lower, yet the description adds substantive context: creation happens in a single undo step, unspecified settings fall back to tool defaults, and the return shape [{guid, type} | {error}] is disclosed even though no output schema exists. Not exhaustive (no auth/permission notes) but genuinely additive.

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 dense but well-ordered paragraph that front-loads what is created and the base-line modes before descending into fields, defaults and return value. Every sentence carries information; it is long 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?

For a two-parameter, high-coverage creation tool with no output schema, the description covers construction modes, units, defaults, one-undo-step behavior, return format and the follow-up editing tools. Only minor gaps (idempotency/pagination-free bulk limits) remain.

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

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

Schema coverage is 100%, so the baseline is 3; the description raises it by clarifying semantics the schema doesn't spell out — primarySpacing as module width along the wall, secondarySpacing as module height, meters for coordinates, degrees for angles, and current-story defaulting.

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 ('Creates curtain walls') and distinguishes the two construction modes ('begin'/'end' straight vs 'path' polyline/curved). It also names the two sibling tools it is not, so an agent can route without opening either 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 routes post-creation editing to modify_curtain_wall_parts (single panels/frames) and modify_curtain_walls (height/grid/classes), which is real when-to-use guidance. It does not, however, state exclusions against neighboring creation tools like create_walls, so it stops short of full 5-level 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 the mutation profile (non-read-only, non-destructive, non-idempotent). The description adds useful behavior beyond annotations: it is one undo step, returns a specific array shape, and tells the agent to open the resulting detail with open_view.

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 with no filler; the window fallback, boundary semantics, return shape, and follow-up action are all compactly stated.

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 create tool with a deep nested schema and no output schema, the description supplies the return shape, follow-up action, and core region/marker semantics. It omits undoName meaning and some defaults, but the nested schema covers most parameter detail.

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 nested schema descriptions already define box, polygon, markerPosition, storyIndex, and other properties in detail. The description restates boundary and marker semantics but does not explain undoName, and with top-level schema description coverage reported at 0%, it leaves a top-level parameter gap unfilled.

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 ('Creates') and resource ('detail markers'), with the active-window scope and fallback to the floor plan. This clearly distinguishes it from sibling creation tools such as create_sections or create_elevations.

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

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

It gives clear usage context: the current floor plan/section/elevation, or the floor plan when another window is active, and it points to open_view for the follow-up. It does not name when to choose this over sibling creation tools, but the context is explicit.

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 readOnly=false, destructive=false, idempotent=false; the description adds real behavior beyond them: the whole call is 'one undo step', unresolved linked points silently fall back to static with a 'warning', and a single failing item does not abort the rest. It also documents per-item error returns and input-order correspondence.

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: purpose, then point model, then units, then placement, then alternatives, then return shape. Every sentence carries information, though the middle associative-point explanation is one long parenthetical that takes a re-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?

For a complex mutation tool with no output schema, the description covers everything an agent needs: creation semantics, units, placement rules, fallback behavior, partial-failure tolerance, the wall alternative, and an inline description of the returned array shape.

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 coverage is reported as 0% (the sole 'dimensions' param wraps a deeply-annotated item schema), so the description must carry the burden and does: it spells out the three point forms ({x,y}, {element, at}, {element, x, y}), the anchor-listing prerequisite via get_dimension_anchors, projection semantics, and the m vs paper-mm unit split.

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 ('Creates linear dimension chains') and immediately scopes it against siblings by naming the alternative ('For walls prefer dimension_walls'). It is trivially distinguishable from create_angle_dimensions, create_radial_dimensions, create_level_dimensions and dimension_walls.

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 routes walls to dimension_walls with the 'Thickness' mode for wall widths, and explains the placement consequence of associative vs static points (Floor Plan with storyIndex vs active window). It stops short of full when-not guidance (e.g. when to prefer modify_dimensions over recreating dimensions).

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 a non-readonly, non-idempotent, non-destructive write. Beyond that, the description adds the 'one undo step' bulk behavior, the return shape [{guid, type} | {error}] in input order, and the defaults fallback — genuinely useful operational detail rather than restating the hints.

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 hard requirements, then orientation/localization/return details. Dense but each sentence carries information; no filler or restated title.

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

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

For a mutation tool with no output schema, the description supplies the missing return format, the bulk-undo behavior, the localization pitfall, and the defaults fallback. A few gaps remain (pagination-like maxItems of 500, error semantics beyond the shape), but an agent has enough 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?

The schema carries rich per-field descriptions, but the prose adds semantics the schema does not state as a rule: position and point are mutually exclusive alternatives, position is measured to the door centre, sillHeight is 'usually 0', and flipped/mirrored control opening and hinge sides. This meaningfully lifts it above the baseline.

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 ('Places doors into walls') and immediately distinguishes itself from related creation tools by naming the host object and the insertion geometry (position vs point). An agent can tell this apart from create_windows/create_openings 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 usage context: each door needs a host wall GUID plus either position or point, unspecified settings fall back to Door tool defaults, and library part names are localized so use search_library_parts (type Door) first. It stops short of stating when to prefer this over sibling creators like create_openings, but the setup conditions 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 establish the mutation profile (readOnly=false, destructive=false, idempotent=false), and the description adds genuinely new behavior: all items commit in one undo step, failures are per-item and non-fatal, and results come back in input order. It stops short of auth/rate-limit context, so a 4 rather than 5.

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 purpose and undo behavior, then the item shape, then the fallback guidance. The long inline type enumeration is bulky but does real work in signaling 'any supported type' breadth; only mildly 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?

With no output schema, the description correctly supplies the return contract ([{guid, type} | {error}] in input order) and the partial-failure rule. Combined with the routing to type-specific tools for field details, an agent has everything needed to call this 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 100% and the schema itself is thin (items typed only by 'type'), so the description carries real weight by explaining the per-item shape ({type:..., ...fields}) and that fields mirror the type-specific tools' documented schemas. It could note the 'undoName' semantics beyond the schema, hence not 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 ('Creates elements of ANY supported type') plus the key scope distinction — a single batch call covering every element type. An agent can immediately tell this apart from the many type-specific create_walls/create_beams/... 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?

Explicitly routes the agent: 'prefer those [type-specific create_* tools]: they document every field.' This is a direct when-to-use-this-vs-alternatives instruction, which is rare and valuable given how many sibling create tools exist.

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, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond this by noting it is 'one undo step' and by summarizing the return shape '[{guid, name, database, ...}]'. It does not mention permission or default-layer side effects, keeping it below a 5.

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 purpose, followed by parameter semantics, a compact example, and the return shape. It is dense but every sentence carries information. Slightly long single-paragraph packing, but 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?

With no output schema, the description responsibly summarizes the return value, and it covers the geometrically tricky parameters that most need explanation. It omits secondary options (layer, storyIndex, renovationStatus, verticalRange/horizontalRange, referenceId), though those are documented in the schema, so the gap is minor.

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 the top-level schema description coverage registers 0%, the description adds real semantic meaning beyond the (nested) field descriptions: begin/end is the elevation line placed outside the building, viewSide looks toward the building, and depth is how far it sees. The worked example (south facade y 0..10) concretely resolves the geometry, which the schema alone does 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: 'Creates elevation markers on the floor plan (one undo step), each with a new elevation viewpoint.' This clearly conveys the output. It does not explicitly distinguish itself from nearby siblings like create_sections or create_interior_elevations, so it falls short of a 5, but an agent can identify the core purpose 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?

Usage is implied rather than stated: the note that begin/end must be 'placed OUTSIDE the building' is an operational constraint, but there is no explicit 'use this when you need X, use create_sections instead' guidance. No conditions or exclusions relative to the many sibling creation tools are provided.

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 cover safety (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds substantial context beyond them: the exact output shape per item including the 'replaced?' flag and per-item error object, the name-collision error behavior (replace default false = error), and the Teamwork reservation requirement. This is the kind of behavioral detail the annotations 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?

Three dense sentences, front-loaded with the core action and sources, then the mutual-exclusivity rule with its prerequisite, then the output contract. No filler; every clause carries actionable information.

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

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

For a single nested-array parameter tool with no output schema, the description supplies the return format, the error/replace semantics, the prerequisite tool call, and the Teamwork locking caveat. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a constraint the schema does not encode: exactly one of element / toolDefaults per item. It also clarifies that tool defaults come from set_tool_defaults, linking the parameter to a sibling tool's state.

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 ('Creates'), the resource ('favorites in the Favorites palette'), and the two supported sources (placed element vs tool defaults). This distinguishes it from sibling favorites tools like get_favorites, apply_favorite, and rename_favorite, which manage rather than create.

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: each item needs exactly one of element/toolDefaults, and to build from scratch the agent must call set_tool_defaults first; it also flags the Teamwork prerequisite of reserving the 'Favorites' object set. It stops short of naming when to prefer an alternative sibling (e.g. apply_favorite) or when not to use it, but the usage context is clear.

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

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

Annotations only declare readOnlyHint=false / destructiveHint=false / idempotentHint=false; the description adds real behavioral context: single undo step, per-item result shape in input order, one failing item does not abort the others, and Russian-localized naming caveats. Nothing contradicts 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?

Front-loaded with the core purpose and packed with dense parenthetical examples; every sentence carries information, but the single sprawling paragraph mixes type semantics, copying, return values, and localization, making it harder to scan than a structured list would be.

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?

No output schema exists, yet the description spells out the return shape `{results: [{index, name, guid, created} | {existed} | {error}]}` and partial-failure behavior. Combined with the indexing/collision guidance, it is complete for a complex destructive-adjacent attribute creation 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?

Goes well beyond the schema with worked examples: percent: 25, bitmapPattern '55AA55AA55AA55AA' = 50%, vector hatch {name:'Diagonal 2mm', lines:[{angle:45, spacing:2}]}, and the scaleWithPlan meter-vs-mm reinterpretation ({angle:0, spacing:0.3} tile grid). These examples clarify units and semantics the schema alone leaves 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?

Opens with a specific verb+resource ('Creates fill types') and immediately enumerates the concrete kinds supported (Solid, Empty, Vector, LinearGradient, RadialGradient, Image). This lets an agent distinguish it from siblings like create_hatches, create_surfaces, and create_line_types without opening any 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?

States where fills are consumed ('building materials (cutFill), hatches, zone/slab cover fills') and routes the agent to get_attributes before looking up localized names, plus duplicate_attributes/basedOn for copying Symbol fills. Clear usage context, though it doesn't explicitly state when NOT to use this tool versus create_hatches/create_surfaces.

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=false, idempotentHint=false), which only confirm this is a non-idempotent write, the description discloses rich behavior: placement into the ACTIVE window's database with window-type constraints, storyIndex default to current story, and critically the partial-failure contract ("one failing item does not stop the others") plus the return shape [{guid, type} | {error}] in input order.

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?

It is a single dense paragraph, but it is front-loaded with the core purpose and then layers on the necessary caveats (localized names, active-window placement, return/error semantics). Every sentence carries operational weight, though the run-on length 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?

With no output schema, the description takes on full responsibility and delivers: it explains the return format, partial-failure behavior, window/story placement rules, attribute localization, and follow-up read/modify tools. 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 description coverage is 100%, so the schema already documents every field (polygon, fillType, orientation, areaText, etc.). The description paraphrases these fields and adds the localized-attribute caveat, but adds little syntax or meaning beyond what the schema carries, so the baseline 3 applies.

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

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

The description opens with a specific verb+resource: "Creates 2D fill polygons (Archicad 'Fill' tool)", then enumerates the key aspects (polygon, arcs/holes, Fill pattern vs building material, pens, orientation, area text). This clearly distinguishes it from siblings like create_fills (attribute creation) and create_elements, so an agent can select it 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 names related tools and their roles: get_attributes to list localized attribute names, get_element_details to read back, modify_elements to change later, and it specifies where elements land (active window, storyIndex default, 3D window cannot hold 2D elements). It gives clear context but stops short of an explicit when-to-use-this-vs-sibling rule.

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 a non-read-only, non-idempotent, non-destructive local write, and the description adds genuinely new behavior: per-item partial failure semantics ('one failing item does not stop the others'), the return shape [{guid, type} | {error}] in input order, and the active-window storage rule. This exceeds what the annotations 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-loads the core action, then window/scoping rules, then return semantics and lifecycle pointers. Dense but every clause carries operational information; 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?

There is no output schema, yet the description supplies the return contract and failure behavior. Combined with full schema coverage and annotations, an agent has everything needed to call this 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 100%, so the baseline is 3, but the description adds defaulting behavior for storyIndex ('default: current story') and clarifies that height is elevation in meters useful for 3D/section snapping. It also ties field names to modify_elements, adding cross-tool naming context.

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 precise verb+resource ('Places hotspots (snap points) at 2D positions') with units and an explicit purpose ('reference/snap points for later drawing'). It is easily distinguished from sibling creation tools like create_elements, create_lines, or create_details.

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?

Names the lifecycle alternatives explicitly ('Change them later with modify_elements'; 'read them back with get_element_details') and states the environmental constraint (elements go into the ACTIVE window; a 3D window cannot hold 2D elements). An agent knows both when to call it and where its output lives.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, but the description adds real context beyond them: the operation is 'one undo step', it is not idempotent in practice (wrong-facing views must be recreated), and it returns a guid/segment structure. That is meaningful, non-obvious behavioral detail.

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

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

Purpose is front-loaded, then mechanism, then parameters, then return shape and next step. Dense but each clause carries information; a single compact paragraph 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?

With no output schema, the description usefully supplies the return shape ([{guid, name, segments:[{index, name, database}]}]) and the follow-up call (open_view with element, segmentIndex). Combined with annotations covering the safety profile, an agent has enough to call and chain it correctly; only undoName and the many optional marker fields go unmentioned.

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 coverage is 0% and undoName is undocumented anywhere, so the description carries some burden. It does add meaning for the key nested fields ('points' as a wall polyline, depth as per-segment view depth in m, closed for all walls), though the nested schema descriptions already state most of this.

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 ('Creates interior elevation markers') and explains the mechanism (polyline along room walls, one view per segment). It does not explicitly distinguish itself from siblings like create_elevations, create_sections, or create_details, so sibling differentiation is left to inference.

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 operational usage hints: points should run along the inside of walls, closed:true covers all walls, and a wrong-facing view is fixed by reversing the point order. It also routes to open_view for the follow-up step. However, it never states when to use this instead of create_elevations/create_sections or any precondition/exclusion.

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 readOnly=false, destructive=false, idempotent=false, so the safety profile is partly covered. The description adds valuable non-annotation context: it constitutes 'one undo step', supports optional comments/attachments, and guarantees results are returned 'in input order'. It doesn't state permission/auth requirements or rollback specifics.

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 use case in a single dense sentence, followed by an output-shape block. The output specification is verbose but earns its place since no output schema exists; overall it is efficient with minimal waste.

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?

No output schema exists, so the description correctly compensates by spelling out the return structure and its input-order guarantee. Combined with 100% schema coverage and annotations, this is nearly complete; only auth/permission behavior is unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents name, attach types, comments, parentIssue, tagText, and undoName in detail. The description only gestures at 'comments and attached elements' at a high level, adding little beyond the schema — the baseline 3 applies.

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 ('Creates') and resource ('issues in the Issue Manager') with scope ('one or more') and optional sub-content (comments, attached elements). An agent can clearly distinguish this from siblings like get_issues, delete_issue, add_issue_comment, and 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?

Explicitly frames the use case — reporting model problems (clashes, missing data, review notes) so the user sees them in Archicad and can export to BCF. This is strong positive guidance, but it names no alternative or when-not-to-use condition (e.g. versus add_issue_comment for existing issues).

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

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

Annotations already declare the operation is a write (readOnlyHint=false) and non-destructive, but the description adds critical behavior beyond that: returns [{guid, type} | {error}] in input order, one failing item does not stop others, parent and class of an existing label cannot be changed (delete and recreate required), and active-window placement rules including that a 3D window cannot hold 2D 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?

The description is a single dense paragraph but front-loaded with the core action and organized logically from basic purpose to associative/independent details, leader mechanics, label class differences, placement context, and return behavior. Every sentence adds value for this complex tool, though bullet points or clearer segmentation would improve scanability.

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 a large nested input schema, no output schema, and moderate complexity, the description covers all essential context: how to create associative vs independent labels, leader construction, text vs symbol label requirements, active-window constraints, error handling, and post-creation modification/readback. Nothing critical for correct invocation 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 100% schema description coverage, the schema already documents each parameter. The description still adds meaningful semantics: explains the leader geometry sequence (begin arrow point -> middle -> end text), clarifies when to use text vs runs, notes that omitting 'end' on associative labels uses Archicad's default position, and links symbol labels to libraryPart and gdlParameters with search_library_parts. It does not cover every field (e.g., justification, renovationStatus), but key relationships are made explicit.

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 ('Places labels') and immediately distinguishes associative vs independent labels, leader lines, and text vs symbol label classes. It differentiates from sibling create_texts by noting shared style fields while clearly positioning this tool as the label creator.

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 when to use this tool: describes where labels land (active window, floor plan vs section/elevation), how to find library parts for symbol labels, and how to later modify or read them back. However, it lacks explicit when-not or direct alternatives (e.g., 'use create_texts instead when you need plain text without a leader').

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

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

Annotations already declare the safety profile (not read-only, not destructive, not idempotent), and the description adds real value on top: the operation is 'in one undo step' (atomicity) and returns '[{guid, type} | {error}]' (return/error shape). These behavioral facts are not derivable from the annotations, though permission/context requirements are unaddressed.

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

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

Front-loaded with purpose, then extra fields, then the name-lookup pointer, a usage tip, and the return shape. Every sentence carries distinct information with no padding, and the ordering matches how an agent would build the call.

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

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

For a non-idempotent mutation tool with no output schema, the description supplies the return shape, undo atomicity, the library-part lookup path, and the cross-reference to create_objects. It is close to complete; only authorization/precondition context 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 description coverage is 100%, so baseline is 3; the description still adds meaning by framing the parameter set as 'same fields as create_objects plus lightOn, lightColor {red, green, blue} (0..1) and lightIntensity', orienting the agent to the inherited-vs-new fields. The lightColor range and the elevation formula reinforce rather than merely restate the schema.

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

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

States a specific verb (Places) and resource (lamps), then defines lamps precisely as 'light-emitting GDL library parts of type Lamp' with examples. It explicitly distinguishes itself from the sibling create_objects by naming the extra light fields, so an agent can tell them apart without opening either 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 guidance: find names with search_library_parts {type: 'Lamp'}, notes names are localized, and supplies a practical elevation heuristic for ceiling lights. It does not explicitly state when to prefer this over generic create_objects, so it falls just short of full when/when-not coverage.

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 non-destructive, non-idempotent mutation, but the description adds substantial behavior beyond that: the default captures the current state, overrides apply in order, the operation runs in one undo step, the return shape is given in detail, and partial failures do not stop other items. This is rich transparency for a complex batch mutation.

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 purpose, then default behavior, an example, the activation alternative, undo behavior, return format, and localization note. Every sentence contributes distinct operational value 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?

For a complex batch mutation tool with no output schema, the description covers the default base state, ordering, undo, return shape, partial failure semantics, localization prerequisite, and the sibling activation tool. Nothing essential for correct invocation 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 50% and the top-level layerCombinations array has no schema description, so the tool description compensates by explaining the default state capture and by giving a concrete example of the layers override pattern. It adds meaningful workflow semantics beyond the schema, though it does not cover every nested parameter detail.

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

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

States a specific verb and resource ('Creates layer combinations') and immediately defines what a layer combination is (saved sets of layer visibility/lock/wireframe/intersection states). It distinguishes the tool from its activation sibling by naming apply_layer_combination, so an agent can tell creation from application without opening the schema.

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

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

Gives clear context: use apply_layer_combination to activate one, and look existing attributes up with get_attributes first because names are localized. It does not explicitly state when to create versus modify or when not to use this tool, but the routing guidance is solid.

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 cover the safety profile; the description goes well beyond by disclosing defaults (visible/unlocked, intersection group 1), the single-undo-step behavior, partial-failure semantics ('one failing item does not stop the others'), and the localization caveat for Russian Archicad. The full return shape is spelled out, which is essential since no output schema exists.

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?

Sentences are dense but front-loaded: the core action and defaults come first, then workflow, then return/failure behavior, then the localization note. Every sentence carries information, though the return-shape sentence is unusually long.

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

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

For a creation tool with no output schema and only 2 top-level parameters, the description covers purpose, defaults, cross-tool usage, partial-failure handling, and return structure. Nothing an agent needs to invoke it correctly is missing.

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

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

With ~50% schema description coverage, the description compensates by surfacing defaults not stated in the schema (intersection group 1, visible/unlocked) and the ifExists/existed:true semantics. It does not explain basedOn, wireframe, or folder, but the schema documents those inline, so the description adds meaningful value above the schema.

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

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

The description opens with a specific verb+resource ('Creates layers') and immediately qualifies scope with defaults (visible/unlocked, intersection group 1). It distinguishes this attribute-creation tool from siblings like create_layer_combinations and create_attributes by naming the exact follow-up tools (create_*/modify_elements).

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

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

It clearly states the workflow context ('Then place elements on them with the layer field of any create_*/modify_elements tool') and a prerequisite ('look existing attributes up with get_attributes first'). It lacks an explicit when-not-to-use or a named alternative for attribute creation, so it falls short of a 5.

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

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

Beyond the annotations, which already disclose that this is a non-readonly, non-destructive, non-idempotent mutation, the description adds substantial behavioral context: paper size and margins come from the master and are shared, the layout ID follows subset numbering unless customLayoutNumbering is true, and new layouts are inserted as the FIRST child. It also describes the output shape, including an optional 'ignored?' field. This is rich disclosure for a creation 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 front-loaded with the core action and every sentence contributes distinct, non-redundant information: master selection, output format, numbering behavior, insertion order, and next steps. Despite its length, there is no filler, and the nested schema references are purposeful.

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 complexity, the annotations that cover safety hints, and the absence of an output schema, the description is complete enough for an agent to call it correctly. It explains required context (master, parent), output shape, numbering rules, insertion position, and subsequent actions, leaving no critical ambiguity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining that paper size and margins come from the master, how customLayoutNumbering changes ID assignment, and that parent defaults to the Layout Book root. It does not explain doNotIncludeInNumbering or provide additional naming syntax, but overall it adds useful interpretation.

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: 'Creates a layout (sheet) in the Layout Book from a master layout, inside a subset (or the Layout Book root).' This clearly distinguishes it from sibling tools like create_layout_subset, which creates subsets rather than layouts. An agent can identify the tool's core action 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?

The description provides clear context for choosing a master layout ('pick a master with the wanted size') and points to get_layout_settings and get_navigator_tree for master IDs. It also mentions using move_navigator_item to reorder and documentation tools to place drawings. However, it does not explicitly state when to use this tool versus alternatives or any conditions under which it should not be used.

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

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

Annotations already declare the safe, non-idempotent, non-destructive write profile, so the bar is lower. The description adds substantive behavior beyond that: how layout IDs are composed ([upper prefix][own prefix][number in numberingStyle, from startAt]), the continuation option, and the return shape ({subsetId}).

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 and resource come first, followed by numbering mechanics and output. The ID-format sentence is complex but earns its place by documenting the core behavior; little 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 12-parameter tool with no output schema, the description covers the parent default, ID generation, continuation, the {subsetId} return, and a verification path. The main gap is that the many boolean flags (autoNumber, customNumbering, includeToIDSequence) are left entirely to the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes further by showing a concrete worked example of how ownPrefix, numberingStyle, and startAt combine (A-01, A-02...), giving meaning beyond the isolated field descriptions.

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

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

States a specific verb ('Creates') and resource ('a subset (folder with its own numbering) in the Layout Book'), and the numbering feature distinguishes it from siblings like create_layout and create_view_map_folder. An agent can tell what it produces 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?

Provides implied usage via the default parent (root) and a post-creation verification tip ('Check the resulting IDs with get_navigator_tree'). However, it never states when to choose this over alternatives such as create_layout or create_view_map_folder, so selection guidance is only 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 cover mutation (readOnlyHint=false), idempotency, and openness. The description adds valuable context beyond that: 'one undo step', placement rules, unit conventions, default settings inherited from the Level Dimension tool, and the return shape including error objects.

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

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

Front-loaded with purpose, then moves through modes, placement, units, defaults, and return format. It is dense but every sentence adds necessary operational detail; no filler. Slightly long, but justified by the tool's complexity.

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

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

Given a single complex array parameter and no output schema, the description covers the essential behavioral and return information: what markers show, where they go, unit expectations, default inheritance, and the returned array shape. Minor gaps remain around permissions and every nested setting, but the schema handles those.

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 top-level parameter 'levelDimensions' has no schema description (coverage 0%), so the description must compensate. It explains the three marker modes tied to 'position', 'element', and 'level'/'static', specifies units (m, degrees, paper mm), and notes that storyIndex defaults to the current story. Nested schema descriptions handle the remaining settings.

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 ('Places') and resource ('level (elevation) dimension markers'), and distinguishes the tool from sibling dimension creators (create_dimensions, create_angle_dimensions, etc.) by specifying level dimensions. The three value modes (story/element/static) make the purpose even more precise.

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

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

Usage is implied by the purpose statement, and the description gives placement context (element markers on Floor Plan, others in active window) and defaults. However, it does not explicitly say when to choose this tool over sibling dimension tools or other alternatives, nor does it state exclusions.

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

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

With annotations covering the safety profile, the description still adds real behavioral detail: overwrite:true replaces an existing embedded part of the same name and existing placed instances keep their link and update, which is a non-obvious mutation consequence. It also discloses defaults (type Object / subtype ModelElement, automatic ZZYZX parameter, default script2D), the return shape, and the failure mode ('GDL errors show up as missing geometry').

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 prose is front-loaded (purpose and return first, then usage, defaults, verification, and reference) and every line is information-dense. The embedded GDL quick reference is large, but given there is no output schema and no separate reference resource, it earns its place; the only cost is that the description is long for a tool blurb.

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 an 18-parameter, deeply nested, write-type tool with no output schema, the description covers purpose, defaults, overwrite semantics, return value, verification workflow, and the GDL syntax needed to populate the script fields. An agent has everything required to invoke it correctly and to validate the result.

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 already 100%, so the schema carries most parameter meaning. The description nevertheless adds semantics the schema does not: the automatic ZZYZX height parameter behavior, the default 2D script for objects/lamps, subtype defaults by type, and a full GDL quick reference that makes the scripts/parameters fields usable. This exceeds the baseline 3 but does not re-explain every individual field.

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 names a specific verb and resource ('Creates a custom GDL library part ... in the project's EMBEDDED library from GDL scripts and a parameter list') and even states the return shape and the downstream consumers (create_objects / create_lamps). This clearly separates it from sibling placement tools like create_objects, create_lamps, and change_library_part.

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?

'Use it for anything the standard library lacks (custom furniture, built-ins, fixtures, signage, parametric equipment)' gives a concrete when-to-use condition, and the overwrite:true note plus the 'Verify with get_library_part_scripts, then place it' workflow adds practical context. It stops short of an explicit when-not-to-use / alternative (e.g., modify an existing part instead), so it is a strong 4 rather than a 5.

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

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

Beyond the annotations (readOnly=false, destructive=false, idempotent=false), it discloses 'one undo step', that elements go into the active window's database, that a 3D window cannot hold them, and partial-failure semantics ('one failing item does not stop the others'). This is exactly the behavioral context annotations cannot express.

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 core action leads, then per-item fields, then placement scope, then the alternative, then return semantics. Every clause carries distinct information 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?

For a batch-creation tool with no output schema, it fully describes the return shape ([{guid, type} | {error}] in input order), partial failure behavior, and follow-up tools. 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: units (meters for points, mm for lineWeight), that unspecified settings inherit from the Line tool defaults, and the enumerated optional fields. It stops short of explaining the pen/lineType resolution rules beyond what the schema already says.

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 ('Draws straight 2D lines') and distinguishes itself from siblings by naming create_polylines for connected segments. An agent can tell it apart from create_arcs/create_polylines/create_walls without opening any 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 routing: use create_polylines for connected segments, modify_elements with the same field names to change, get_element_details to read back. Also clarifies placement context (active window, floor plan vs section, 3D window cannot hold 2D elements).

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 adds real behavioral content beyond that: it runs in one undo step, one failing item does not abort the batch, results come back in input order, and it warns that names are localized (Russian Archicad). This is exactly the 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?

Front-loaded with the core action and dense with parenthetical asides that all carry information, but the run-on packing of units, copy hints, undo, return shape, and localization makes it harder to scan than a short bulleted form would.

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?

No output schema exists, yet the description specifies the return shape per item (index, name, guid, created/existed/error), ordering, and partial-failure behavior. Combined with schemas for the inputs, an agent has everything needed to call this 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 only ~50% schema description coverage, the description compensates by explaining the non-obvious unit semantics (millimeters on paper vs meters in the model when scaleWithPlan is true) and giving a worked dash/gap example. Unit ambiguity is the highest-risk parameter detail here, and it is addressed.

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 the exact resource (line types) and enumerates the three kinds it can produce (Solid, Dashed, Symbol) with concrete field shapes. An agent can distinguish this from generic attribute creators like duplicate_attributes or create_composites 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?

Offers a technique alternative ('easier: copy an existing symbol line with basedOn') and a prerequisite workflow ('look existing attributes up with get_attributes first'), naming a sibling tool. It stops short of stating when not to use it or how it compares to other attribute-creation siblings, so it is clear context rather than a full routing rule.

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?

Adds substantial behavior beyond the annotations: one undo step, a failing item does not stop the others, results returned in input order as {guid,type}|{error}, unspecified settings fall back to tool defaults, and attribute names are localized. These are exactly the traits that let an agent predict side effects and error handling.

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 purpose and a worked example, then units and return semantics. It is dense and slightly run-on but every sentence carries information; nothing 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 batch-create tool with no output schema and no nested-object support, the description covers geometry semantics, defaults, error/return shape, undo scope, and the localized-name lookup dependency — everything an agent needs 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 100% so the baseline is 3, but the description adds real meaning: z is relative to mesh 'level', levelLines are ridges/contours that shape the interior, skirtLevel is depth below the base plane, and units are meters/degrees in project coordinates. It complements rather than duplicates the schema.

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

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

Opens with a specific verb+resource ('Creates meshes (terrain / site surfaces)') and immediately pins the domain, distinguishing it from sibling create tools like create_slabs, create_shells, and modify_meshes. The example further anchors what the output element is.

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

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

Usage is implied through the geometry guidance and the explicit pointer to read results back with get_element_details and to look up localized names via get_attributes, but it never states when to prefer this over the generic create_elements or when NOT to use it (e.g. vs modify_meshes for existing meshes).

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 annotations (which only cover readOnly/destructive/idempotent) by disclosing the one-undo-step atomicity, the closed-to-Solid / open-to-Surface rule, coordinate frame (x/y project, z relative to home story), surface assignment inheritance, and default resolution from tool defaults. The return contract '[{guid, type} | {error}] in input order' is a valuable behavioral detail.

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

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

Front-loaded with the core action, then dense geometry semantics that each earn their place for such a complex tool. It is long but not padded; only the multi-clause geometry sentence is heavy, which is defensible given three distinct body representations.

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 supplies the return shape and order, coordinates, defaults, and the Solid/Surface determination rule. For a 2-param but deeply nested geometry tool, this covers everything an agent needs to construct a valid call.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds genuine interpretive value: it explains the three mutually-exclusive geometry kinds, counter-clockwise face winding, meters/degrees units, and per-face surface inheritance ('surface' covers the rest). This meaningfully supplements rather than repeats the schema.

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

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

States a specific verb and resource with a clarifying gloss: 'Creates morphs (free-form 3D bodies) in one undo step.' It distinguishes morphs from other body-creating siblings (create_shells, create_slabs, create_meshes) by defining them as free-form 3D bodies, so an agent can identify the correct tool without opening schemas.

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

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

Explicitly routes to related tools: read back with get_element_details/get_morph_geometry, change with modify_morphs, combine with solid_operation. It gives clear context for the create-modify-read workflow, though it does not explicitly exclude alternative body creators (shells/slabs/meshes) or state prerequisites.

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?

Adds substantial context beyond the annotations: that all placements occur in one undo step (with undoName), that the return is [{guid, type} | {error}] in input order (per-item failures, not all-or-nothing), and that GDL param changes run the part's parameter script like the settings dialog. Localized-name gotcha is 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?

Front-loads the core action and the required fields, then packs the optional list efficiently. The long 'Optional:' enumeration is dense but each item is distinct, so little is wasted; slight tightness could be improved.

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 supplies the return shape and error model, names required fields and units, and covers sibling routing and follow-up tools. An agent has everything needed to call it correctly on the first try.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns extra by flagging that libraryPart names are LOCALIZED (must be discovered via search_library_parts), giving units (position/elevation in meters, angle degrees CCW), and mapping sizeA/sizeB/height to GDL A/B/ZZYZX 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 a specific verb and resource ('Places GDL objects ... in one undo step') and enumerates what counts (furniture, equipment, fixtures, custom parts). It explicitly differentiates from siblings: lamps go to create_lamps, doors/windows to the opening tools, and later edits to modify_elements.

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

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

Gives the required prerequisite ('find them first with search_library_parts {query, type: 'Object'}'), names the exclusive alternatives (create_lamps, opening tools), and routes post-creation changes to modify_elements / set_gdl_parameters / change_library_part.

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 establish that this is a non-destructive, non-idempotent write. The description adds substantial behavior beyond that: wall openings extrude horizontally while slab/roof openings extrude vertically, 'Infinite' limit cuts through the whole host, default constraint varies by host type, and the return shape is [{guid, type} | {error}] in input order. This is rich, non-obvious operational detail.

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

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

Dense but front-loaded: the core purpose comes first, then requirements, then host-specific behavior, then the API limitation and return format. Every sentence carries information, though the heavy parenthetical clauses make it slightly packed rather than crisply scannable.

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 compensates by describing the return value. It covers valid hosts, effective required fields, host-dependent defaults and orientations, the polygonal-shape limitation, and the anchor/position mechanics, so an agent has what it needs 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?

The schema marks only 'owner' as required, so the description carries real weight by stating that width (and height unless circular) are also needed, and that 'point' or, for walls, 'position' must be supplied. It also clarifies the point/position relationship and the bottomElevation meaning for horizontal wall openings, adding semantics not guaranteed by the schema alone.

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 (creates Opening-tool openings) and defines them concretely as rectangular/circular extrusion bodies that cut holes through a host, listing the valid hosts. This clearly differentiates it from siblings like create_windows, create_doors, create_skylights, and generic create_elements.

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

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

Gives clear when-to-use context: shafts through slabs, service holes in walls/beams, and it explains that walls take 'position' while other hosts take 'point'. It also rules out custom polygonal shapes via the Archicad 26 API limitation. It does not, however, route the agent among alternatives such as create_windows/create_doors/modify_openings/get_host_openings.

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 (which only give readOnly=false, destructive=false, idempotent=false, openWorld=false). It discloses the return shape '[{guid, type} | {error}] in input order', partial-failure semantics (one item failing does not stop the others), the non-replaceability of the image, and the placement-window constraints.

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, with purpose stated first and constraints after. The final sentence crams returns plus the modify_elements advice together, which slightly hurts scannability, but every sentence contributes 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?

No output schema exists, yet the description supplies the return shape and partial-failure behavior, plus the active-window/3D-window constraint the agent needs to call it correctly. Given the annotations cover the safety profile and the schema documents the nested item fields, nothing material is missing.

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

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

Schema coverage is already 100%, so the schema carries the parameters. The description still adds real semantics beyond it: size in meters via width and/or height with aspect ratio preserved when only one is given, pixel-size fallback with bottom-left corner at position when no size is set, and the optional anchor/angle/mirrored/transparent/name list.

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 ('Places raster images (PNG, JPEG, GIF, TIFF, BMP) from ABSOLUTE file paths') and gives concrete use cases (logo on a layout, site photo on a worksheet). This cleanly distinguishes it from sibling placement tools like place_drawing and place_hotlink.

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

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

Explains the operative context explicitly: elements go into the ACTIVE window database, with storyIndex on floor plans and section/elevation/detail/worksheet/layout otherwise, and that a 3D window cannot hold 2D elements. It also notes that position/size/angle can later be changed with modify_elements and the image itself cannot be replaced, which is useful routing context. It stops short of naming a direct alternative tool by 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 declare the write/non-destructive profile, and the description adds substantial context beyond them: active-window targeting, storyIndex defaulting, the constraint that 3D windows cannot hold 2D elements, and the partial-failure return contract. This is exactly the kind of behavioral detail 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?

Dense but well front-loaded: geometry description first, then usage, then window/targeting constraints, then return contract and follow-up tools. Every sentence carries information, though the run-on structure could be tightened.

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

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

For a complex creation tool with no output schema, the description covers targeting, defaults, partial-failure behavior, and the return shape ([{guid, type} | {error}] in input order). Nothing essential to correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds non-redundant semantics: the arc edge indexing rule and the critical note that modifying 'arcs' or 'closed' requires resending 'points' because geometry is replaced. That goes beyond what the schema states.

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 ('Draws 2D polylines') and details the geometry model (straight + curved segments, open/closed), which distinguishes it from siblings like create_lines, create_arcs, and create_circles. An agent can tell it apart without opening the schema.

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

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

Gives clear context ('Ideal for outlines, symbols and room-separator chains (zoneBoundary: true)') and names follow-up tools (modify_elements, get_element_details). It stops short of explicitly saying when to prefer this over create_lines/create_arcs, only noting shared style fields.

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 annotations covering readOnly/destructive/idempotent/openWorld, the description adds substantive behavior: one undo step, return shape {results: [...]} in input order, failure isolation ('one failing item does not stop the others'), and localization caveat. This goes well beyond the structured hints.

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 long but front-loads purpose, then an example, then limitations and return behavior; each sentence supplies actionable detail. The example is valuable for a geometry-heavy tool, though the text could be trimmed slightly.

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 complex (nested shapes, no output schema), and the description supplies the missing return contract, undo semantics, failure isolation, and a usage caveat. With annotations covering safety, this is sufficiently complete for correct invocation.

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

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

Schema coverage is 50%, so the description carries moderate burden. It provides a concrete polygon example with meter coordinates and x/y orientation, plus hints for core/buildingMaterial, but it does not explain every nested parameter (folder, pen indices, ifExists override) that the schema itself describes.

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 'Creates' and resource 'complex profiles', enumerates the element types they apply to (walls, beams, columns, handrails), and notes they are built from polygons. This clearly distinguishes it from sibling attribute creators like create_composites or create_fills.

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 tells the agent how to use the result ('Use it with the profile field of walls/columns/beams') and to look up localized names with get_attributes first. It also notes 'basedOn copies an existing profile' and that stretch zones/parameters are unsupported, but does not compare it against alternative attribute creation 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?

Goes well beyond the annotations: 'one undo step' (matching NOT idempotent), the IMPORTANT availability caveat that unclassified elements never show custom properties, that missing groups are auto-created (createMissingGroups default true), the callable type list, and the exact return shape including warnings. These are real behavioral traits not present in the annotations or schema.

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

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

Front-loaded with purpose and the critical caveat, then the workflow and return shape. It is dense but every clause carries information; there is minor overlap with the schema's own field descriptions, which slightly inflates length.

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 3-param mutation tool with no output schema and no nested-object signal, the description supplies the missing return contract ({results:[...guid, name, group, type, availabilityCount, warnings} | {error}] in input order) and the classification-availability semantics an agent must know 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 67%, and the description adds cross-parameter meaning the schema only states per-field: that availability governs which classifications see the property, that option sets need enumValues, and that groups are created when missing. It does not fully compensate for the uncovered parameter documentation, but it meaningfully supplements 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?

States a specific verb and resource ('Creates user-defined (custom) properties') and characterizes the scope ('any value type, option sets, defaults, availability per classification'), which distinguishes it from siblings like create_property_groups, modify_property_definitions, and set_property_values. An agent can tell immediately what this tool builds.

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 names a follow-up tool ('Then set values with set_property_values'), which routes the workflow, but it never states when to use this versus modify_property_definitions, delete_property_definitions, or import_property_definitions_xml, nor any preconditions/exclusions. Usage is implied rather than explicit.

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 behavior beyond the annotations: single undo step, existing-name handling via alreadyExisted, and the full return shape. However, it declares the operation '(idempotent)' while the annotation sets idempotentHint: false, a direct conflict on the repeat-call semantics that an agent would rely on for retry logic.

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?

Four dense sentences, front-loaded with the verb+resource before behavior and return value. Almost every clause earns its place; the return-type sentence is slightly terse but useful given no output schema.

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 supplies the return shape, the idempotent-return flag, and the sibling interaction – exactly the gaps structured fields leave. Remaining gaps are permissions/error semantics beyond the union type, which are minor for an annotated, non-destructive mutation.

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 only 50% (name documented, the nested description field and undoName's role only partially). The description adds no parameter-level meaning at all – it never explains the 500-item cap, the per-group description field, or how undoName interacts with the stated 'one undo step' behavior. With low coverage it should compensate and does 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 and resource ('Creates user-defined property groups') and disambiguates the resource with a parenthetical ('the folders of the Property Manager'). It also names the sibling it overlaps with (create_property_definitions), so an agent can separate the two without reading either 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 gives a concrete routing rule: create_property_definitions already creates missing groups itself, implying this tool is for standalone group creation. It never states exclusions negatively (e.g. when to prefer the definitions tool), but the overlap note is real guidance rather than none.

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 cover the safety profile (write, non-destructive, non-idempotent, closed-world). The description adds genuinely useful behavior beyond that: 'one undo step' (atomic), the radius-verification/associative linkage, the drawing/window placement constraints, and the return payload shape. Auth requirements and failure modes are not discussed, keeping it short of a 5.

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?

Four dense sentences, front-loaded with purpose and the atomic-undo fact, then constraints, then return shape. Minimal waste; the quoted field names are terse and functional rather than 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 high-complexity geometry tool with a deeply nested schema, the description covers placement constraints, associativity/verification, and even the return format in the absence of an output schema. Combined with annotations that carry the safety profile, an agent has what it needs 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?

The reported coverage is 0% at the top level, but the nested item schema is actually exhaustively documented (at, lineEnd, prefix, text, pens, fonts, etc.). The description re-explains 'at' (where it touches the arc) and 'lineEnd' (where the radial line ends) in slightly more intuitive terms, but adds little the schema does not already provide.

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?

Clear, specific verb+resource: it 'dimensions the radius' of arcs, circles, curved walls or beams. This distinguishes it well from the many sibling dimension tools (create_dimensions, create_angle_dimensions, create_level_dimensions, dimension_walls), though it does not explicitly name those alternatives.

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

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

Provides real prerequisites: walls/beams must be on the Floor Plan, arcs/circles must be in the active window's drawing, and the radius is verified against the element. However, it never states when to prefer this over create_dimensions/dimension_walls or other dimensioning tools, so routing guidance is implied rather than explicit.

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=false, destructiveHint=false, idempotentHint=false), the description discloses that creation happens 'in one undo step', that unspecified settings inherit the Railing tool defaults, that the story defaults to the current story, and the error/return shape. This is substantive behavioral context.

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

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

Dense but front-loaded, leading with the core verb and geometry, then parameters, then a tip and return value. Slightly long as a single block, but nearly every clause 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?

No output schema exists, yet the description explains the return value ([{guid, type} | {error}]) and points to get_element_details for sub-element GUIDs. Combined with units, undo semantics, and default-inheritance behavior, it is complete enough for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: coordinates in meters, angles in degrees, z carrying slope, arcs for curves, closing a railing by repeating the first point, and the meaning of height/bottomOffset/reference line side. It lifts parameter meaning above the schema text.

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 ('Creates') and resource ('railings') and immediately scopes it to a reference line, distinguishing it from modify_railings and create_stairs in the sibling list. An agent knows exactly what geometry it produces.

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 a concrete routing tip (use a stair's leftBoundary/rightBoundary from get_element_details as the path to guard a stair) and explains the begin/end vs path choice. It does not explicitly state when NOT to use it (e.g. use modify_railings for existing railings), so it falls short of full 5.

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

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

Annotations already declare it is a non-readonly, non-idempotent, non-destructive write with openWorldHint false. The description goes further: it says results are returned as [{guid, type} | {error}] in input order, that all items are one undo step, that a failing item does not stop the others, and that attribute names are localized and should be looked up with get_attributes. That 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 dense but well-organized: a short purpose statement followed by SinglePlane and MultiPlane explanations, a concrete example, units/attribution notes, and return/undo behavior. Most sentences earn their place, though some schema-level parameter descriptions are repeated, adding minor 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?

The description covers both modes, gives a concrete example, states units, defaults, localization, and return/undo semantics. For a complex multi-mode creation tool with no output schema it is strong, though it could mention whether stories matter for placement or that roof elements can be modified later with modify_roofs.

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

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

Schema description coverage is 100%, so the schema already documents every parameter and nested field. The description adds conceptual context (pivotLine is the eaves line, pivotPolygon is usually the wall outline, slopeAngle is in degrees) but does not provide syntax or format beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource ('Creates roofs') and then precisely delineates the two modes, SinglePlane and MultiPlane, including the geometric parameters that distinguish them. Siblings create_walls/create_slabs are separate element types, and the tool's domain is unmistakable.

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

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

The description explains the two roof-class options and how to build a gable roof from two SinglePlane roofs, which is implicit usage guidance. However, it never states when to choose this tool over create_slabs or create_shells, nor does it give prerequisites like story context or attribute lookup for a first-time caller beyond mentioning get_attributes.

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 this is not read-only, not idempotent, and not destructive, but the description adds important behavioral context: it creates one section viewpoint per item, groups the operation into a single undo step, and specifies the return array with either success objects or errors. It does not mention rate limits or authorization needs, but for a creation tool it provides solid additional transparency beyond 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 purpose and packs a lot of useful information into a compact form. It lists item fields in a somewhat run-on manner, but every sentence contributes (purpose, item details, return shape, follow-up actions). It is appropriately sized for a complex creation 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?

Given the rich nested schema and the annotations covering safety, the description adds valuable context: the undo grouping, return array format, and next steps with open_view and capture_view. It misses explaining the 'undoName' top-level parameter and does not mention the max of 100 items, but overall it is complete enough for an agent 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 reported as 0% for top-level parameters, so the description must compensate. It mentions many item fields (begin/end, viewSide, depth, vertical range, name, referenceId, storyIndex/layer) but these are already documented in the nested schema, and it omits the top-level 'undoName' parameter entirely. It also leaves out some item fields like elementId, horizontalRange, and renovationStatus, so it fails to fully cover the parameter space.

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: 'Creates section markers (cut planes) on the floor plan, each with its own new section viewpoint'. It distinguishes clearly from sibling tools like create_elevations (sections vs elevations) and create_details. An agent can identify exactly what this tool does without opening the schema.

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

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

The description implies usage by describing creation of sections and then suggests follow-up actions: 'Open one with open_view {element: guid} and look at it with capture_view.' It does not state when to use this tool versus alternatives (e.g., create_elevations) or any prerequisites like an active floor plan view. Usage is implied but not explicitly guided.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds crucial behavioral context beyond that: it returns [{guid, type} | {error}] in input order, groups changes into one undo step, and a failing item does not stop others. It also notes that unspecified settings come from tool defaults and that attribute names are localized.

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 long but front-loaded with the core purpose, then systematically covers modes, placement guidance, units, localization, and return behavior. Every sentence carries useful information for this complex tool, though it could be slightly tighter by avoiding some repetition of schema details.

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

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

For a complex 3D creation tool with 100% schema coverage and annotations present, the description is complete: it explains return values and error handling, cross-references get_element_details and get_attributes, specifies units and coordinate system, and describes undo grouping. No critical information is missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter in detail. The description adds example JSON and clarifies the interpretation of 'profile' across modes, but this largely repeats what the schema already states per parameter. Baseline 3 is appropriate when the schema does the heavy lifting.

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