ifc_validate

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.