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

Annotations already cover read-only and closed-world behavior. The description adds useful behavioral context by saying the return is the verbatim original STEP line, which matters because there is no output schema. It does not mention missing-ID errors or truncation/line-cap 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?

Two tight sentences with the purpose front-loaded and no wasted wording. Every phrase contributes either the tool's output or its intended use.

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

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

For a simple read-only two-parameter tool, the description covers purpose, return value, and usage well enough to call it correctly. Minor gaps remain around truncation/max_lines behavior and not-found cases, though the schema documents `max_lines`.

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 both parameters are already documented. The description reinforces that `id` is a GlobalId but adds no syntax, format, or `max_lines` details beyond the schema, 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?

It states a specific verb and resource: return the original file text behind a GlobalId, specifically the STEP line that declares it verbatim. This clearly distinguishes it from sibling BIM query/aggregation tools as a provenance/citation lookup.

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 explicit when-to-use guidance: verify a claim before repeating it, and when a reviewer asks where a number came from. It does not name alternatives or state 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?

Annotations already cover the read-only/open-world safety profile, but the description goes further by disclosing how unresolved ids surface in `not_found` and that 'no such element' and 'hidden by policy' are deliberately conflated to avoid leaking filtered shape. That is genuinely non-obvious behavioral context an agent could not infer 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?

Two short paragraphs, front-loaded with the core action followed by the error-semantics detail. The em-dash clause about not leaking filtered shape is slightly ornate but still load-bearing 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, so the description must convey what comes back — and it does: full property sets, quantities, materials, plus the `not_found` bucket. With only two well-documented parameters, 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 both `ids` and `max_ids` are already documented, and the description adds little parameter-level detail beyond calling them 'named GlobalIds'. Baseline 3 is appropriate when the schema carries the 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?

Specific verb ('expands') plus resource ('named GlobalIds into every property set, quantity and material'), and it explicitly frames itself as the drill-down counterpart to the compact list queries, which cleanly separates it from siblings like bim_elements_by_type and bim_property_values.

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 'drill-down half of the loop' framing tells the agent this follows a list query, which is clear usage context. It stops short of naming a specific sibling or stating exclusions (e.g. when to prefer bim_property_values instead), so it falls just below the top score.

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 read-only, closed-world safety profile, and the description adds real context beyond them: that all property sets are searched by default due to exporter inconsistency, and that the matched set and value are returned with each hit. It does not discuss result limits or ordering, so not 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 with the example, followed by a short paragraph on the one non-obvious parameter decision. Every sentence carries information; nothing is 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?

With 9 parameters, no output schema, and a rich schema, the description covers the trickiest decision (pset) and hints at the return payload. It stops short of describing the full result shape or caps, which matters because there is no output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it justifies the `pset` default and shows a multi-parameter combination in the example. The `op` semantics are only illustrated via `exists`, not fully explained.

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 (find) and resource (elements matching a property condition), then anchors it with a concrete example (fire-rated doors on level 3). An agent can distinguish this from bim_elements_by_type or bim_elements_missing_property based on the property-condition framing.

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 worked example implicitly shows when this tool is appropriate, and it gives clear guidance to omit `pset` by default. However it never explicitly contrasts itself with siblings like bim_elements_by_type or bim_elements_missing_property, leaving the agent to infer the boundary.

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 safety (readOnlyHint) and closed-world scope, so the description is free to add value — and it does: subtype inclusion is the default and expands the result set, which is a real behavioral trait an agent could get wrong. It also discloses the return shape ("one compact row per element with its GlobalId citation"), which is useful with no output schema present.

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

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

Three short sentences, front-loaded with the operation, then the subtype caveat, then the return shape. Nothing is padding and the most error-prone behavior (subtype expansion) lands early.

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 characterizes the response as compact rows carrying GlobalId citations. For a read-only filter tool with fully documented params this is close to complete; only the interaction with sibling tools is left 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 coverage is 100%, so all five parameters are already documented — including the include_subtypes default that the description restates. The description adds no format or edge-case detail beyond the schema, 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?

States a specific verb and resource ("List elements of an IFC type") plus its filter scope, and the subtype note makes the semantics concrete with an example (`IfcBuiltElement` returns walls, slabs, doors). It separates itself from bim_elements_by_property by being type-driven, but never names a sibling to make the distinction explicit.

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

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

Usage is implied by the phrase "optionally narrowed by storey, name or PredefinedType", which hints at the type-first lookup pattern. There is no explicit when-to-use vs. bim_elements_by_property / bim_element_detail guidance and no stated exclusions or 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. Beyond that, the description discloses non-obvious internal behavior: plain material, material list, layer set, profile set and constituent set associations are all resolved before the check, which tells the agent it will not get false positives from layered or constituent-based assignments.

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, front-loaded with the qualifying condition, and the enumeration of material association kinds is dense but earns its place by defining the predicate. Slightly wordy for what could be a single clause, 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?

For a read-only, no-output-schema query tool with five optional filters, the description supplies the semantic definition an agent needs and points at the most useful filter. It omits return shape (element list contents) and any result-size limits, which is a modest gap given there is no output 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 all five filters are already documented in the schema, and the description only elaborates on `type` (its role in scoping the query) with an example. That is a genuine but small increment over structured data, 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?

The description states a specific resource (elements unreachable by IfcRelAssociatesMaterial) and defines the exact predicate that makes an element qualify, which goes well beyond restating the title. It does not explicitly contrast itself with the near-identical sibling bim_elements_missing_property, so an agent must infer that this is the material-specific variant.

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?

"Restrict with `type` to ask the question that actually matters, e.g. only IfcWall and IfcSlab" gives concrete usage advice on narrowing scope. However, it never says when to choose this tool over bim_elements_missing_property or how to combine it with storey/name filters, leaving alternatives unaddressed.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real semantic context beyond the schema: why the empty-string default exists (exporters write '' for "not filled in"), which tells the agent how matching actually behaves. It does not describe return shape or result volume, keeping it below 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?

Two sentences, front-loaded with the inverse-of-sibling framing followed by the rationale for the default. The clause about exporters is not filler – it justifies a behavioral default the agent might otherwise override.

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 8 parameters, full schema coverage and no output schema, the description covers the key conceptual gap (what "missing" means). It stops short of saying what comes back – a list of elements, a count, or grouped results – which an agent would want for an audit query.

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 eight parameters are already documented, establishing a baseline of 3. The description only reinforces the property/type pairing in prose and adds no syntax, format, or interaction detail (e.g. how pset and property combine) 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 operation (find elements with no value for a given field) and explicitly frames itself as the inverse of a named sibling, bim_elements_by_property. An agent can distinguish it from that sibling and from bim_elements_by_type 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 a clear use case ("the one most model-audit questions reduce to") and names the complementary tool it inverts, which routes selection. It does not state explicit exclusions or when to prefer a different audit tool such as bim_property_values, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful context beyond them: results reflect the *visible* model 'after policy' (i.e., filtered by access policy), and the call is 'cheap, bounded'. That policy-filtering nuance is exactly the kind of behavioral trait 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?

Two sentences, front-loaded with the returned contents and then the usage recommendation; no filler. The phrase 'cheap, bounded' is slightly marketing-flavored but still earns its place as cost 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?

There is no output schema, but the description explicitly enumerates the return contents, and the policy-filtering caveat plus boundedness tells the agent what to expect. Nothing essential for calling this 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 100%, so top_psets and top_types are already documented with defaults. The description adds no additional meaning about these parameters, which is acceptable at the baseline when the schema carries the load.

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 enumerates exactly what the tool returns (schema, authoring application, units, storeys, element counts by type) and explicitly positions itself as the discovery/first-call tool versus the more targeted siblings like bim_elements_by_type or bim_property_values. An agent can tell what this does and why it differs from the other bim_* tools without opening the schema.

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

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

It gives a clear when-to-use signal ('the right first call... before it starts guessing names at them'), which is strong positive guidance. It does not name a when-not case or name specific sibling alternatives to avoid, so it falls just short of a 5.

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

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

Annotations only declare readOnlyHint/openWorldHint=false; the description adds genuinely non-obvious behavior — that real models spell the same concept inconsistently across property sets, which is exactly why the tool exists. It also discloses the return shape (each distinct value, a count, up to three example GlobalIds). It doesn't discuss cost/performance on large models, so not 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 with the motivating question, then the sequencing instruction, then the return shape — each sentence carries distinct information. The fire-rating example is concrete and earns its space as the justification for existence.

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 format (value + count + sample GlobalIds) and the core motivation, which is enough to call it correctly. It doesn't cover interaction between flags like include_missing/include_subtypes or behavior on very large models, but nothing critical is missing for a read-only tabulation 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 all eight parameters are documented there (pset, type, storey, property, name_contains, include_missing, predefined_type, include_subtypes). The description adds no parameter-level meaning beyond 'this field', 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?

Opens with a concrete question the tool answers ('What values does this field actually take?') and names the resource (distinct property values with counts and sample GlobalIds). It explicitly distinguishes itself from the sibling bim_elements_by_property, 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 prescribes sequencing: 'Run this before elements_by_property rather than guessing.' That is a clear when-to-use plus a named alternative. It stops short of stating when *not* to use it (e.g., for absent values, where bim_elements_missing_property may fit), so it is strong 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?

Annotations already cover the safety profile (readOnlyHint, openWorldHint=false), and the description adds genuinely non-obvious behavior: unit normalization to m/m2/m3 and, crucially, that each group reports `without_quantity` alongside `count` so incomplete totals are self-evident. It does not say what happens when the named quantity is absent everywhere or on error, 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?

Opens with the operation and grouping before any caveat, which is the right ordering. The second paragraph's aphorism about 40 of 200 walls is slightly editorial but does justify the `without_quantity` field, so it mostly earns 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?

With no output schema, the description carries the return-value burden and does so for the main fields (group key, count, without_quantity). It stops short of describing the shape of group labels or behavior on unknown quantity names, but an agent has enough to call it correctly.

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

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

Schema coverage is 100%, so every parameter is already documented in the schema, and the description adds only the example quantity names and the unit-conversion note. Baseline 3 is appropriate since the schema does the heavy lifting.

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 ('Total a named quantity ... over a selection') plus the grouping axis, which is more precise than any sibling like bim_model_summary or bim_property_values. An agent can tell this is the aggregation tool versus the listing/detail tools without opening the schema.

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

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

The description implies when to use it (you want a rolled-up total rather than per-element values) and names the grouping options, but never states exclusions or points to an alternative such as bim_property_values for distinct values or bim_elements_by_type for per-element listings. Usage is inferable rather than directed.

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 (readOnlyHint=true, openWorldHint=false), yet the description adds real behavior: areas are normalized to square metres after unit conversion, and spaces lacking any area quantity land in `notes` instead of being silently dropped. That 'no answer vs. no data' distinction is exactly the kind of context an agent cannot infer from annotations, though result ordering and any result caps remain 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?

Three short paragraphs: purpose first, then unit semantics, then quantity resolution. Every sentence carries information an agent would otherwise have to guess, and nothing is repeated from the schema or annotations.

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 eight optional parameters and no output schema, the description covers the highest-risk ambiguities: unit normalization and where unmeasured spaces end up. Minor gaps remain — the defaults for include_subtypes and the interaction between `type` and `storey` filtering 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 coverage is 100%, so baseline would be 3, but the description goes beyond it by explaining that min/max thresholds are applied post-unit-conversion and by spelling out the resolution order for `quantity` (explicit, then NetFloorArea, GrossFloorArea, Area). That fallback chain is not derivable from the schema's one-line parameter description.

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

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

States a specific verb and resource ('Spaces whose floor area falls inside a range') plus a concrete example ('rooms below the 8 m2 minimum'). The area-threshold framing cleanly separates it from siblings like bim_quantity_rollup and bim_elements_by_type, which do not filter on area ranges.

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 example use case makes the intended scenario concrete, and the quantity fallback paragraph tells the agent how the tool behaves when the caller is unsure which quantity to name. It does not, however, explicitly name an alternative sibling or state when-not to use it (e.g. vs. bim_quantity_rollup for aggregated totals).

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 readOnlyHint=true / openWorldHint=false, the description discloses a genuinely non-obvious behavior: element counts reflect only *visible* elements, so policy-scoped models report zero rather than revealing hidden content. That caveat prevents a real misinterpretation of zero counts. It stops short of describing depth defaults or output shape in 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?

Two tightly packed sentences with no wasted words; the identity of the tool comes first and the important visibility caveat follows. 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 does the necessary work of characterizing the return value as a hierarchy with level names, GlobalIds, and element counts, plus the visibility caveat. It could be slightly more explicit about hierarchy shape (storeys vs. spaces) but is sufficient to call 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 both parameters (max_depth, with_element_ids) are documented in the schema, so the baseline is 3. The description's mention of GlobalIds loosely gestures at with_element_ids but adds no semantics about max_depth or what depth means in this hierarchy.

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 identifies the tool as returning the containment hierarchy and explains concretely that it 'turns "level 3" into a GlobalId', which tells an agent exactly what resource is produced. It lacks a crisp verb phrase ('return/describe') but the outcome is unambiguous and clearly distinct from siblings like bim_model_summary or bim_elements_by_type.

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 implies a sequencing rule ('the map an agent needs before it can ask anything storey-shaped'), which is useful guidance but purely implicit. No sibling is named as an alternative, and no when-not-to-use condition is stated, so the agent must infer the routing from the phrasing.

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