Spatial structure

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.