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

With no annotations, the description carries the full behavioral burden, and it delivers: it warns that zooming can still leave the element hidden behind other geometry and explains how to use isolate to work around it. It also states the side effect on the viewport and that a restore step is needed.

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 first sentence front-loads the core operation and result, while the second paragraph adds only the crucial caveat and remediation. No filler or redundant restatement of the 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?

For a tool with no annotations and no output schema, the description covers the essential workflow, the main failure mode, and the cleanup call. It leaves minor gaps such as the format of the returned image/focus payload and the semantics of width/timeout, but the key usage context is complete.

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

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

Schema description coverage is 0%, so the description must compensate. It explains guid through 'this GlobalId' and isolate through 'hide everything else', but width and timeout receive no semantic guidance beyond their schema titles and defaults.

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 concrete action sequence—select by GlobalId, zoom viewport, return image and focus target—which distinguishes it from siblings like bl_screenshot or ifc_get_element. The verb and resource are specific, and the return payload is stated.

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

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

It gives clear operational context: the tool's zoom does not guarantee visibility, and the description tells the agent when to pass isolate=true and to follow with bl_isolate(restore=true). It does not explicitly spell out when to avoid this tool or prefer an alternative, 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?

With no annotations, the description carries the behavioral burden. It transparently discloses that hiding is viewport-only, does not touch IFC data, and can be reversed with restore=true. It does not cover edge cases like null guids or persistent state across calls, but the most important safety and reversibility traits are explicit.

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

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

The description is three compact sentences with no filler. The core behavior is front-loaded, followed by the restore mechanism and the non-destructive guarantee.

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

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

The description covers the main operation and reversible behavior, but with no output schema and no annotations, it leaves some context implicit. An agent still has to infer the meaning of width and timeout, how the returned image is represented, and what happens when guids is null.

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

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

Schema description coverage is 0%, so the description must compensate for all four parameters. It clarifies that guids are the GlobalIds to keep visible and that restore=true unhides everything, but it adds no meaning for width or timeout. This is partial compensation for the schema gap.

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

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

The description states a clear action: hide everything except the specified GlobalIds and return the image. This distinguishes it from siblings like bl_screenshot or bl_focus_element by describing the isolation behavior and its output.

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 a practical usage context: use this to isolate certain elements and produce an image, and pass restore=true to undo the hiding. It does not explicitly name when not to use it or mention alternatives, but the context is clear and no exclusions are needed.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the most important behavior: the tool works only on in-memory IFC data and preserves unsaved edits, unlike a disk reload. It does not discuss error handling, undo behavior, or side effects on selection/view state, but the key safety-relevant trait is clearly 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?

Three short sentences with the primary purpose front-loaded, a prominent caveat, and a clear usage instruction. There is no filler or redundant restatement of the tool name, and every sentence adds value.

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 two optional parameters and an output schema, the description covers the central call semantics and the most dangerous misunderstanding (disk reload). The main gap is the timeout parameter's meaning, and there is no mention of what happens when no IFC data is in memory. Still, an agent can invoke the tool correctly in the common case.

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

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

The description clearly explains the guids parameter: pass it to reload only specified elements, or omit it to reload every IFC-backed object. However, the timeout parameter is never mentioned, and schema description coverage is 0%, so its unit and purpose are left to inference. The description partially compensates for the schema gap but not fully.

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 pair: 'Rebuild the viewport geometry from the IFC data currently in memory.' It also explicitly distinguishes itself from a disk reload, so an agent immediately understands what the tool does and what it does not do. This is clear, actionable, and non-tautological.

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 a clear when-not-to-use signal: it is not a reload from disk because that would discard unsaved edits. It also instructs when to pass guids versus when to omit them to act on all IFC-backed objects. It does not explicitly name alternative sibling tools, but the caution and usage conditions are strong enough for correct selection.

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

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

With no annotations provided, the description carries the disclosure burden and does so well: it reveals the render method (OpenGL viewport render), output format (PNG), image sizing behavior (longest side clamped to 320..2048), and aspect-ratio preservation. It does not disclose timeout behavior or error handling, but the core behavioral traits are clear.

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

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

The description is compact and front-loaded: purpose first, then clarifying details, then parameter constraints. Every sentence adds value and there is no filler.

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

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

For a simple tool with no required parameters and no output schema, this description is nearly complete: it covers the action, output format, image constraints, and key sizing semantics. The only notable gap is the absence of any explanation for `timeout`, which leaves a small but real 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 0%, so the description must compensate. It thoroughly documents `width`, including clamping and aspect-ratio behavior, which is more than the schema provides. However, it says nothing about `timeout`, leaving its units, meaning, and failure behavior undocumented.

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

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

The description uses a specific verb and resource: 'Render the current 3D viewport and return the image.' This clearly distinguishes it from sibling tools like bl_set_view or ifc tools, and there is no other screenshot/render sibling competing for the same action.

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

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

The description implies when to use it: when you need a clean image of the 3D viewport. It also explicitly states what it is not ('not a screen grab, so no panels or other windows appear'), which helps an agent choose it over a full-UI capture. However, it does not explicitly name alternatives or state when not to use it.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions that the camera is pointed and an image is returned, but it does not disclose that the current viewport state is changed, what the returned image contains, or how width, timeout, and frame_all affect behavior.

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

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

The description is highly concise and front-loaded, with the core purpose stated first and the direction values listed immediately after. No filler or redundancy exists, though the brevity leaves little room for needed guidance.

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 four parameters, no annotations, no output schema, and sibling tools like bl_screenshot, the description is incomplete. It omits parameter semantics for three parameters, side effects, return value details, and any selection guidance among siblings.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It adds meaning only to 'direction' by listing valid values; width, timeout, and frame_all remain entirely unexplained.

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

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

The description states a specific action: point the viewport camera along one axis and return the image. It is clear and names the key 'direction' parameter, but it does not explicitly differentiate itself from the sibling tool bl_screenshot, which also returns an image.

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?

There is no guidance on when to use this tool versus alternatives such as bl_screenshot. The description lists direction options but provides no context about prerequisites, sequencing, or cases where another tool should be preferred.

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

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

No annotations are provided, so the description carries the full burden. It transparently discloses a significant behavioral side-effect: calling this tool syncs the session, making Blender's loaded project the authority and causing ifc_open to refuse opening different files. This is critical behavioral detail beyond a simple status check. It also warns about potential version mismatch issues. The description goes beyond a simple status report to explain the side effects and underlying risk, which is excellent. However, it doesn't mention output format (but output schema exists). Minor deduction for not describing side effects on other tools beyond ifc_open (e.g., what happens if no project is loaded).

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 well-structured into three paragraphs: first, what status it returns; second, the version comparison and why it matters; third, the session synchronization side-effect. Each paragraph adds distinct value, and the information is front-loaded with the core purpose. No wordiness; every sentence contributes.

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 (status check + version comparison + session sync), the description covers all major aspects. The output schema exists, so return values are documented elsewhere. The side-effect on other tools is explained, but one might want to know what happens if no project is loaded (does it sync?) or if Blender is unreachable (does it time out?). The timeout parameter is not explained, but its default is given. Overall, quite complete for a status tool with significant side effects.

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

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

The only parameter is 'timeout' with a default of 30. The schema provides the name, type, default, but no description. The description does not mention timeout at all. However, since timeout is a common parameter for network operations, the schema itself (name and default) gives enough context. The description covers 0% of the parameters, but since there is only one self-explanatory parameter, the gap is minimal. Given 1 parameter, the description could have mentioned it, but the schema's 'timeout' with default 30 is fairly clear. Score 4 because it's still a useful parameter but self-explanatory by name.

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

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

The description clearly states what the tool does: reports whether Blender is reachable, which Bonsai and ifcopenshell versions it runs, and which IFC file is open. It also explicitly compares ifcopenshell builds and warns about mismatches. This is specific, uses a clear verb ('whether', 'compares', 'warns'), and distinguishes itself from other tools by focusing on status and session synchronization.

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 when this tool is relevant: it is useful to check status before operations and it explicitly mentions the session synchronization effect—that once Blender loads a project, it becomes authoritative and affects other tools. However, it doesn't explicitly say 'use this when you need to verify environment consistency' or 'don't use this if you just need file info'—but the context implies it. No direct alternatives are named, but the sibling tools are evident. Slight deduction for not explicitly stating when not to use it.

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

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

With no annotations, the description carries the behavioral disclosure burden. It does disclose a meaningful trait: the operation is create-or-extend, so an existing pset is not destroyed. However, it does not state whether existing property values are overwritten, what side effects occur, or what happens when required inputs are invalid.

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 sentence, front-loaded with the action and resource, with no filler. It is as concise as a description can be while conveying the core create-or-extend behavior.

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 has five parameters, no annotations, and a description that only covers the pset/properties core. Missing context includes how the target entity is resolved, what query/guid/max_elements control, and error or edge-case behavior, so an agent cannot reliably call it without inspecting the output schema or experimenting.

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

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

Schema description coverage is 0% and there are five parameters, but the description only loosely maps to pset and properties. guid, query, and max_elements are left completely unexplained, so the description does not compensate for the schema gap.

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

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

The description uses a specific verb ('Create') and names the resource ('property set'), and adds the key nuance that existing sets are extended rather than replaced. It is clear on its own, though it does not explicitly distinguish itself from siblings like ifc_set_pset_value or ifc_remove_pset.

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?

There is no guidance on when to choose this tool over alternatives, nor any mention of prerequisites such as an open IFC model or how the target element is selected. The 'extend if exists' behavior implies a use case, but the conditions are left to inference.

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

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

With no annotations present, the description carries the behavioral disclosure burden. It discloses the non-obvious risk of silent changes to all elements sharing a profile, explains that the refusal reports the count, and states that tessellated geometry is refused outright with no tessellation workaround. This is strong, though it does not mention success-side effects like persistence or undo.

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

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

The description is compact, front-loaded with the core operation, and each of the three short paragraphs earns its place: purpose, shared-geometry refusal, and tessellated-geometry refusal. There is no redundant or filler content.

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 scope and refusal behavior well, but it leaves a critical gap around how to supply parameters in the params object, and it does not clarify persistence or reversibility. Output schema exists, so return-value detail is not required, but the missing param guidance prevents the description from being fully complete.

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

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

Schema description coverage is 0%, so the description had to compensate for the three parameters. It explains apply_to_all semantically and warns about shared profiles, but the central 'params' object remains undefined: no valid keys, value types, or example are given. An agent would struggle to construct the primary payload correctly.

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

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

The opening sentence states a specific verb and resource: 'Change the parameters of an element's parameterised profile.' This clearly distinguishes it from sibling tools that edit attributes, psets, or placements. It stops short of a 5 because it does not explicitly name or contrast with any sibling tool.

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

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

The description gives clear usage context: it refuses on shared geometry and tessellated geometry, and it explicitly tells the caller to pass apply_to_all=true only when changing all sharing elements is intended. It lacks explicit alternative-tool routing for those refusal cases, but the when-not conditions are unambiguous.

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

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

With no annotations, the description carries full behavioral burden. It adds meaningful traits beyond the bare result list: placement is absolute ('whole nested IfcLocalPlacement chain has been multiplied through') and shared IfcRepresentationMap geometry is flagged with a share count. It does not explicitly state read-only behavior, but the info-suffix and return-only wording make the non-mutating nature reasonably clear.

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

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

The description is compact, front-loaded with the purpose, uses a scannable list for outputs, and adds exactly one high-value behavioral clarification in a second short paragraph. No sentences repeat the tool name or schema fields.

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

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

The description covers the return semantics well, and an output schema exists for return details, but input selection is under-specified. An agent cannot determine how to target an element (guid vs step_id), what the identifier contract is, or how include_metrics changes the result. Given three optional-looking parameters, this is a significant completeness gap.

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

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

Schema description coverage is 0%, so the description must compensate for the three parameters. It never explains how guid and step_id identify the element, that one of them is required, what happens when both/neither are supplied, or what include_metrics=false does to the listed metrics. Listing volume and surface area only weakly hints at the include_metrics 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?

The description opens with a specific resource ('Geometry of one element') and enumerates concrete outputs (representation type, items, profile parameters, 4x4 placement, bbox, volume, surface area), so an agent knows exactly what this tool returns. It does not name sibling tools, but the scope ('one element') distinguishes it from model-level or representation-statistics 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 content implies use when per-element geometry detail is needed, but there is no explicit when-to-use/when-not-to-use guidance or mention of alternatives like ifc_get_element or ifc_representation_stats. The absence of exclusions leaves room for an agent to overuse it, but the output list provides enough context for basic selection.

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

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

With no annotations, the description carries the behavioral burden. It discloses the scope of the returned detail and the identifier-based lookup, which is useful. It does not mention behavior when neither identifier is provided, error cases, or confirm that this is a read-only operation, though the 'get' verb implies it.

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

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

The description is two short sentences with no filler. The core purpose and returned content are front-loaded, and the identification method is stated immediately after.

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

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

Given that an output schema exists, the description does not need to explain return values. It covers purpose, identifier options, and content scope. The only notable gap is lack of explicit guidance on the mutual exclusivity or necessity of guid versus step_id.

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

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

Schema description coverage is 0%, so the description must compensate. It maps the two parameters to 'GlobalId' and 'STEP id', giving basic semantic meaning beyond the raw parameter names. It does not specify expected formats, which parameter takes precedence, or that at least one identifier is effectively required.

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

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

The description clearly identifies a specific verb and resource: retrieving full detail for one element. It enumerates the returned content categories (attributes, property sets, quantities, material, type, spatial container), making it easy to distinguish from sibling listing or model-level 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 phrase 'Full detail for one element' implies when to use the tool, and 'Identify it by GlobalId or STEP id' tells the agent what input is needed. However, it does not explicitly compare against alternatives such as ifc_list_entities or ifc_model_info, nor state when not to use this tool.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions pagination and that the real total is always reported alongside the returned page, which is a specific behavioral detail beyond the schema. However, it does not explicitly state that the operation is read-only or mention any side effects, though 'list' implies read-only. The disclosed behavior is useful and covers a key aspect an agent needs to handle responses correctly.

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 sentences: the first states the core purpose and pagination; the second adds a key behavioral detail. It is front-loaded with the main verb and resource, contains no fluff, and every sentence earns its place. Perfectly sized for a tool of this 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 the tool's simplicity (three parameters, one required), the description covers the essential purpose, pagination behavior, and subclass inclusion. Since an output schema exists, the agent can infer return structure without needing it in the description. The only gap is the lack of explicit parameter semantics, but the names and context are fairly self-explanatory. Overall, the description is complete enough for an agent to call this tool correctly in most scenarios.

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

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

The schema has zero description coverage, so the description must compensate. It adds meaning to 'ifc_class' by noting that subclasses are included, and the term 'paginated' relates to the limit and offset parameters. However, it does not explain the exact semantics of limit/offset (e.g., how pagination works, default behavior) beyond what the names imply. The description partially compensates for the schema's lack of detail but does not fully cover all three parameters.

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

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

The description clearly states the tool lists instances of a specific IFC class, includes subclasses, and is paginated. This is a specific verb+resource combination that distinguishes it from sibling tools like ifc_list_property_names (which lists property names) and ifc_spatial_tree (which returns a tree). The scope and behavior are immediately understandable.

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 a clear context for when to use the tool (listing instances of an IFC class) but does not explicitly mention alternatives or conditions when another tool should be used instead. There is no 'when-not' guidance or naming of sibling tools for comparative use. The usage is implied rather than explicitly stated.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It adds meaningful context beyond the name by warning that exporters routinely use nonstandard names and that queries against absent names return empty sets without error. This is valuable behavioral information for an agent.

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 concise and well-structured: a one-sentence core definition, followed by actionable usage guidance and a concrete motivating example. Every sentence earns its place with 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?

For a listing tool with an output schema available, the description covers purpose, timing, and a critical domain quirk. The only real gap is the absence of parameter explanation, but the output schema handles return values and the tool is simple enough that the description is otherwise complete.

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

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

Schema description coverage is 0%, and the description does not mention 'limit' or 'properties_per_set' at all. The names are somewhat self-explanatory, but the description adds no meaning beyond the input schema and does not compensate for the complete lack of schema 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 an exact verb and resource: it lists every property set and property name that actually exists in the file, with occurrence counts. This clearly distinguishes the tool from mutation-oriented siblings like ifc_add_pset and ifc_set_pset_value.

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

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

The description explicitly instructs when to call this tool: 'before writing any property query', with a concrete rationale involving exporter naming deviations and silent empty results. It does not explicitly name alternatives or when-not-to-use conditions, but the guidance is strong and practical.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It reveals the expected outputs but does not state whether the operation is read-only, whether it requires an open model, how limits affect behavior, or whether any side effects or performance concerns exist.

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 entire description is a single front-loaded sentence with no filler. It conveys the core output components immediately and earns its place.

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

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

For a read-style info tool with an output schema and only optional parameters, the description captures the main response surface. However, it leaves the two parameters functionally unexplained and does not mention any preconditions, making it minimally viable rather than complete.

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

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

Schema description coverage is 0%, and the description does not explicitly explain class_limit or storey_limit. The names and the description's mention of a per-class histogram and storey list imply their purpose, but the semantics—such as ordering, truncation, or special values—are left unspecified.

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 the tool returns a model summary, a per-class entity histogram, and the list of storeys—a specific resource and output profile that distinguishes it from siblings like ifc_list_entities or ifc_geometry_info. It lacks an explicit verb like 'retrieves' or 'returns', but the noun phrase is clear enough.

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?

There is no guidance on when to use this tool versus alternatives such as ifc_list_entities or ifc_representation_stats. The description states what it provides but never suggests a scenario, prerequisite, or exclusion, so an agent must infer the use case from the tool name and siblings.

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

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

With no annotations, the description carries the behavioral disclosure burden. It does disclose that the tool translates elements and reports origin before and after, which gives useful observable behavior. However, it does not mention persistence, whether the operation permanently modifies the model, or how selection limits like max_elements affect the action.

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

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

The description is two short sentences with no filler. The core action is front-loaded, units are included, and the output behavior is stated efficiently. Every word earns its place.

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

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

Despite having an output schema, the description omits how targets are chosen and how guid, query, and max_elements relate. An agent must infer selection semantics and mutation behavior, which is incomplete for a tool with six parameters. The 'reports origin before and after' detail helps, but the selection model remains underspecified.

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

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

Schema description coverage is 0%, so the description must compensate, but it only adds units for dx/dy/dz ('delta in metres'). The important selection parameters guid, query, and max_elements are entirely unexplained, including how they interact. This leaves a significant semantic gap for a six-parameter tool.

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

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

The description states a specific verb ('Translate') and resource ('elements'), and specifies units in metres, so an agent can tell this is a translation tool rather than rotation or placement. It also adds an observable output ('Reports origin before and after'), which clarifies the tool's purpose further. It does not explicitly contrast with sibling tools, but the core operation is clear.

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?

There is no guidance on when to use this tool versus ifc_rotate_element, ifc_set_placement, or ifc_set_attribute. The description does not mention how elements are selected via guid, query, or max_elements, nor does it give any conditions or exclusions. Usage context is entirely 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?

No annotations are provided, so the description carries the behavioral disclosure burden. It discloses the return contents, the refusal scenario, and the reason for refusal (avoiding a second, independent copy). It could add more about side effects on the current Blender scene, but the provided behavior is clear and useful.

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

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

The description is compact and front-loaded: the main action is stated first, followed by return-value highlights, then the refusal condition. Every sentence earns its place with no redundant 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 tool with one parameter and an output schema, the description covers the essential context: what the tool does, what it returns, and when it will not operate. The output schema handles return value structure, so the description is complete enough for an agent to call this 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?

The schema has only one 'path' parameter with 0% description coverage. The description connects the parameter to an IFC file but does not explicitly specify path formats, absolute vs. relative paths, or valid file extensions. The parameter is simple enough to be mostly self-explanatory, but the description adds only minimal meaning beyond the schema.

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

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

The description opens with a specific verb and resource: 'Open an IFC file and make it the active model.' This clearly distinguishes the tool from siblings like ifc_model_info, ifc_get_element, or ifc_save, since it is the loading/initialization operation.

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

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

The description implies this tool is used when an IFC file needs to be loaded as the active model, and it provides an explicit when-not condition: it is refused when Blender already holds a model through Bonsai. However, it does not explicitly name alternative tools or contrast with them.

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 no annotations, the description carries the full burden and does disclose important behavior: rebuilding the model into a new file object, the file-replacement requirement, and why blender mode refuses these recipes because Blender's objects would point into the discarded file. It does not discuss reversibility or whether a subsequent save is required, but the key behavioral edge cases are covered.

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

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

The description is compact and front-loaded: one purpose sentence, a recipe list, then two short paragraphs for constraints. Every sentence earns its place without redundancy.

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

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

For a tool with three parameters, multiple recipes, and mode-dependent behavior, the description covers the supported recipes, the args contract, and the important file-replacement constraint. It does not explicitly state whether the in-memory model is mutated and must be saved afterward, but the provided information is sufficient to call the tool correctly in most cases.

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

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

Schema description coverage is 0%, so the description compensates by explaining that `args` uses recipe-defined parameter names and that a wrong name is answered with the accepted list and defaults. It also clarifies the conditional role of allow_file_replacement for the two rebuilding recipes. The recipe list adds meaning that the bare schema lacks.

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

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

The description opens with a specific verb and resource ('Run an ifcpatch recipe over the whole model') and then enumerates the supported recipes. This clearly distinguishes the tool from sibling editing/query tools by stating exactly what it operates on.

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 concrete usage conditions: which recipes need allow_file_replacement=true in standalone mode and that those recipes are refused in blender mode. It does not name alternative sibling tools for different use cases, but the when-to-use and when-not-to-use guidance is clear enough.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It states that a pset is detached, but does not clarify whether the property set is deleted, kept in the model, or how the operation affects associated data. This is a meaningful transparency gap for a mutating operation.

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

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

The description is a single, front-loaded sentence with no filler. It is concise, but the brevity sacrifices essential parameter and usage context.

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 has four parameters, no schema descriptions, and no annotations. The one-sentence description leaves out how to identify the element, how the query parameters work, and what constraints apply, so the description is not complete enough for reliable 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 description coverage is 0%, so the description must compensate for parameter understanding. It only clarifies the meaning of 'pset' implicitly; the roles of 'guid', 'query', and 'max_elements' are completely unexplained, leaving the agent to guess how to target the element.

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

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

The description uses a clear verb (Detach) and specifies both the resource (property set) and the target (an element). This distinguishes it from the sibling ifc_add_pset, which performs the inverse operation, though it does not explicitly name that sibling.

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

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

No guidance is given about when to use this tool versus alternatives such as ifc_add_pset or when detaching is appropriate. The context implies this is the inverse of adding a pset, but that is not explicitly stated.

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

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

No annotations are provided, so the description carries the behavioral disclosure burden. It does convey a read-only, analytical behavior through 'breakdown' and 'lists', and it reveals the output scope. However, it does not disclose potential performance or scanning implications hinted by map_scan_limit, or behavior when no model is open.

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 focused sentences with no filler. It front-loads the key 'whole-file geometry breakdown' concept and lists output dimensions in a compact, scannable manner.

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

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

The output schema covers return value structure, so the description does not need to explain outputs. However, the tool still lacks parameter semantics and usage guidance, which are needed for an agent to customize invocation beyond defaults. This makes it adequate but not complete.

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

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

Schema description coverage is 0%, and the description does not explain any of the three parameters: limit, map_scan_limit, and shared_map_limit. The names and defaults offer partial hints, but 'limit' is ambiguous and no parameter details are provided to compensate for the missing schema 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 clearly identifies a whole-file geometry breakdown by specific dimensions (RepresentationIdentifier/RepresentationType, item class, parametric vs tessellated share). It lacks a direct verb, but 'breakdown' and 'lists' convey the analysis action well. It is sufficiently distinct from sibling tools like ifc_geometry_info by emphasizing file-wide aggregates.

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

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

The description provides no guidance on when to choose this tool over alternatives such as ifc_geometry_info or ifc_model_info. There are no explicit exclusions or conditions, leaving the agent to infer usage context from the tool name and sibling list.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states that all edits since the first edit are discarded, revealing the destructive nature, and adds the Blender-mode reload behavior so memory and disk stay consistent. This is excellent transparency.

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 concise and structured effectively: the first sentence defines the core purpose, and the second adds an important mode-specific behavior. Every sentence earns its place with no redundancy or filler.

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

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

For a zero-parameter tool with no annotations, the description is fully complete. It explains what happens, what is lost, and the special Blender-mode behavior. An output schema exists, so return-value details are not required here.

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?

There are zero parameters, so there is nothing for the description to explain about parameter usage. The baseline for zero-parameter tools applies; the description appropriately focuses on behavior rather than inputs.

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 ('Restore') and a clearly defined resource ('the file from the safety copy taken before this session's first edit'). It is unambiguous about what the tool does and is easily distinguished from siblings like ifc_open, ifc_save, and bl_reload.

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

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

The description makes the usage context clear: it discards every edit since the first edit, so an agent can infer when to invoke it. It does not explicitly name alternatives or state when not to use it, but the effect is described precisely enough to guide selection.

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

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

The description usefully discloses that rotation is around the element's own origin, not the project origin, and that the element spins in place. However, with no annotations and a mutating operation, it does not mention persistence, undo/revert behavior, or effects on the IFC model, which remain unknown.

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

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

Two sentences, zero filler; the core action and the key behavioral nuance are front-loaded. Every sentence earns its place.

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

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

For a mutation with five parameters, none described in the schema, this is incomplete: the agent cannot tell how guid and query select elements or what max_elements does. Output schema exists, so return values are less critical, but selection semantics and side effects are missing.

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

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

Schema description coverage is 0%, and the description only clarifies the axis and the pivot behavior. It adds no meaning for guid, query, max_elements, or degrees (units/sign), so most parameters remain ambiguous.

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

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

The description uses a specific verb ('Rotate'), names the resource ('elements'), and clarifies the rotation frame ('about their own origin, around world x, y or z'). This clearly distinguishes it from movement/placement siblings like ifc_move_element or ifc_set_placement.

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

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

No guidance is provided on when to choose this tool over ifc_move_element, ifc_set_placement, or other manipulation tools. It states what the tool does but not the conditions or alternatives, so an agent receives no routing help.

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 no annotations provided, the description carries the full burden of behavioral disclosure and meets it well. It explicitly states the overwrite-safe default, warns that even the origin file cannot be overwritten without overwrite=true, and explains the reopen-and-check behavior of validate=true.

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

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

Three short paragraphs, each focused on a single concern: the action, the overwrite rule, and the validation behavior. There is no filler or repetition, and the most important information appears first.

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 all three parameters and the meaningful behavioral edge cases for a save operation. An output schema exists, so return-value details do not need to be in the description. The combination of schema and description gives an agent everything needed to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must explain all parameters, and it does. Path is defined as the write target, overwrite is explained with a concrete overwrite condition, and validate is described in terms of reopening and checking. This goes far beyond the bare schema names.

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

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

The description opens with a specific verb and resource: 'Write the model to `path`.' This clearly identifies the action and distinguishes it from sibling tools like ifc_open or ifc_validate. The rest of the description builds on that core purpose without ambiguity.

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

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

The description gives clear practical guidance on when overwrite=true is required and what validate=true does. It does not explicitly compare against sibling tools, but the save-versus-open/validate distinction is self-evident and the parameter usage context is strong.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does not state whether selection replaces or augments the current selection, whether any visual or model state is mutated, or what side effects may occur. The query syntax examples help, but important behavioral context is missing.

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

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

The description is compact and front-loaded, with the essential action stated first. The examples are efficient and directly instructive, with no filler or redundant phrasing.

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

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

Although an output schema exists, the description still omits crucial context for a selection operation: what happens to the previous selection, whether selection is visual or logical, and the exact role of limit/offset. The examples cover query syntax but not enough of the operational context for an agent to use the tool with confidence.

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

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

Schema description coverage is 0%, so the description must compensate. The examples add real meaning for the 'query' parameter by showing valid ifcopenshell selector patterns. However, 'limit' and 'offset' are left to their bare names and defaults, with no explanation of how they behave in the selection 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?

The description clearly identifies the action ('Select elements') and the resource ('an ifcopenshell selector query'), with concrete syntax examples. It does not explicitly differentiate from sibling tools like ifc_get_element or ifc_list_entities, but the query-based selection intent is clear.

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 examples imply when this tool is appropriate: when users need to select elements by IFC type, name pattern, or property value. However, there is no explicit guidance contrasting it with alternatives such as ifc_get_element or ifc_list_entities, and no stated 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 no annotations provided, the description carries the full burden of behavioral disclosure. It conveys that this is a mutating operation and discloses a valuable safety behavior: queries exceeding max_elements are refused with the count, preventing accidental model rewrites. It does not mention reversibility or what happens when both guid and query are omitted, but the disclosed safety guard is genuinely useful.

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 with no filler: the first states the operation and examples, the second explains targeting modes, and the third adds the safety guard. It is front-loaded, skimmable, and every sentence earns its place.

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

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

The description is sufficient for an agent to understand the core call pattern, including single vs. bulk targeting and the safety limit. Since an output schema exists, return-value details are not necessary. The main gaps are exact query syntax and value/attribute constraints, but the essential invocation semantics are present.

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

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

Schema description coverage is 0%, so the description must explain parameters. It usefully covers guid, query, max_elements, and examples of attribute values, but it does not explain the query selector syntax, the accepted value type for 'value', or the full set of legal attribute names. Parameter understanding is therefore partial rather than complete.

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

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

The description names a direct, specific operation ('Set one IFC attribute') and gives concrete examples of affected attribute names like Name, Description, ObjectType, and Tag. It clearly distinguishes its single-attribute scope from sibling tools like ifc_set_pset_value, but does not explicitly name alternatives, so it stops short of top-tier differentiation.

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

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

The description clearly explains the two invocation modes: targeting one element by guid or many by query, and it states the max_elements safety behavior. It does not explicitly compare itself to alternatives such as ifc_patch or ifc_set_pset_value, but the context for setting plain IFC attributes is unambiguous.

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

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

With no annotations provided, the description must disclose behavioral traits. It mentions a 'sharing guard' but does not explain what it entails (e.g., side effects, permissions, reversibility). It also does not indicate whether setting the depth modifies the element permanently or if it triggers re-rendering. This is insufficient for a mutation tool.

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

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

The description is very short (two sentences) and front-loads the core action, which is efficient. However, it under-specifies crucial details expected in a tool description, so brevity is achieved at the cost of usefulness. It is not egregiously verbose, but it misses opportunities to add value.

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 there are 3 parameters, no annotations, and the tool performs a mutation, the description is notably incomplete. It does not explain the sharing guard's implications, the role of 'apply_to_all', or any side effects. Though an output schema exists, the overall context for calling the tool 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 0%, so the description must compensate for the missing parameter meanings. It fails to explain 'guid', 'depth', or 'apply_to_all'. The only hint is that depth is in metres, but even that is not tied to the parameter. An agent cannot infer parameter semantics from this description.

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

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

The description clearly states the action (set) and the resource (extrusion depth) with a unit (metres). It is specific enough to convey the core purpose, but it does not explicitly distinguish it from sibling tools like ifc_edit_profile beyond a passing reference, so it falls short of a 5.

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

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

The phrase 'Same sharing guard as ifc_edit_profile' gives a hint about a constraint but does not explain when to use this tool versus alternatives, nor does it provide prerequisites or exclusions. There is no context about typical use cases or situations where this tool is preferred.

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

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

With no annotations, the description carries the behavioral disclosure burden. It usefully reveals matrix conventions: row-major, translation in the last column in metres, fixed bottom row. However, it does not disclose side effects such as whether the change is in-memory only, whether a save is required, or whether dependent geometry is updated.

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

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

The description is three short sentences with no filler. Purpose comes first, followed by precise format constraints, then a practical hint for retrieving the current matrix. Every sentence earns its place.

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

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

For a two-parameter mutation tool with no annotations, the description explains the purpose and matrix format well, and an output schema covers return values. Still, it omits operational context such as whether the model must be open, whether changes persist only after ifc_save, and whether setting an absolute placement recomputes dependent geometry. These gaps make it solid but not fully complete.

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

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

The input schema has no parameter descriptions (0% coverage), so the description must compensate. It does so strongly for the matrix parameter: 4x4, row-major, translation in the last column in metres, bottom row [0, 0, 0, 1]. The guid parameter is only implied as the element identifier, but the critical matrix semantics are clearly documented.

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

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

The description opens with a specific verb and object: 'Set an element's absolute 4x4 placement matrix.' The word 'absolute' clearly distinguishes this from relative transform siblings like ifc_move_element and ifc_rotate_element, so an agent can tell the intent 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?

The description gives a clear sequencing hint ('Get the current one from ifc_geometry_info') and implies this is for absolute placement, but it never explicitly states when not to use this tool or names alternatives for relative movement/rotation. Usage context is present but mostly implied rather than stated.

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

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

With no annotations, the description carries the full burden and does disclose an important behavioral trait: it 'fails loudly rather than creating a near-miss duplicate'. However, it does not mention side effects, permissions, whether existing values are overwritten, or what the output contains.

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 tight sentences with no filler. The main action is front-loaded, and the prerequisite is stated with a clear reason in the second sentence.

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

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

Despite having an output schema, the description leaves six parameters undocumented and does not explain how guid/query/max_elements govern target selection. The prerequisite hint is valuable but not sufficient for reliable invocation, especially since annotations are 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 0%, and the description only indirectly clarifies pset and property. It says nothing about guid, query, value, or max_elements, leaving the agent to guess how the element is selected or how value should be formatted.

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

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

The description clearly states the action ('Set one property') and the target ('inside an existing property set'), making the core purpose unambiguous. It does not explicitly contrast siblings like ifc_add_pset, but the phrase 'existing property set' helps distinguish it from pset creation/removal.

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 an explicit precondition: run ifc_list_property_names first, with a rationale about exporter naming behavior and failure mode. It lacks explicit statements about when not to use this tool versus alternatives like ifc_set_attribute, but the provided guidance is actionable and context-rich.

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 no annotations, the description carries the full behavioral burden. It does disclose the output shape and that element counts are included, but it stays silent on whether this is read-only, how max_depth or class_limit affect traversal or grouping, and any edge behavior. Some burden therefore remains unmet.

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 compact sentence with no filler, and the core idea—spatial hierarchy with counts—is front-loaded. It is concise, though the noun-phrase form and missing usage/parameter context mean the brevity is partially under-specification.

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 two optional parameters are semantically undocumented, and no annotations clarify safety or scope. Even with an output schema present, the description does not give enough context for an agent to select and configure the call correctly. A usable definition would at least explain what max_depth and class_limit govern.

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

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

Schema description coverage is 0% and the description never mentions max_depth or class_limit. The agent cannot infer what class_limit limits or what max_depth applies to. There is no compensatory parameter documentation anywhere.

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

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

The description names a specific deliverable—the IfcProject→Site→Building→Storey hierarchy with per-node element counts—so an agent can identify what the tool produces. It lacks an explicit operational verb like 'returns' or 'builds', and does not contrast with siblings, so it stops just short of full clarity.

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

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

No guidance is given for when to use this tool versus alternatives such as ifc_model_info, ifc_list_entities, or ifc_geometry_info. The intended use is only implied by the name and output shape; there are no exclusions or alternative pointers.

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?

There are no annotations, so the description carries responsibility for behavioral disclosure. It does disclose that the tool runs ifcopenshell.validate and returns a condensed report rather than raw full output, which is useful. It does not explicitly state that the operation is read-only, whether validation can fail loudly, or whether it depends on an already-loaded IFC model.

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 sentence with no filler. It front-loads the action and packs the output summary efficiently, making every phrase informative.

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 gives the core purpose and output summary, and the presence of an output schema reduces the need to explain return values. However, it omits parameter semantics and usage prerequisites, and with no annotations it does not fully cover operational context. It is adequate for a simple validation tool but has clear gaps.

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

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

Schema description coverage is 0%, and the tool description never mentions 'limit' or 'express_rules'. The description adds no meaning beyond the parameter names and defaults, leaving important semantics unresolved, such as what limit applies to and what enabling express rules actually does.

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

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

The description starts with a specific verb and resource ('Run ifcopenshell.validate') and spells out exactly what the tool returns: a condensed report with counts by level, frequent messages, and a page of individual issues. It is clear what the tool does, though it does not explicitly distinguish itself from sibling tools; no sibling is obviously a validation tool, so this is a minor gap.

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 intended use is implied by the verb 'validate' and the tool name, so an agent can infer it is for checking an IFC model. However, the description gives no explicit when-to-use guidance, no mention of prerequisites such as an open IFC model, and does not contrast with related inspection tools like ifc_model_info or ifc_representation_stats.

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