Check an IFC file against IDS requirements

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

Annotations already declare readOnlyHint and openWorldHint=false, so the safety profile is known; the description reinforces it with 'Runs locally; nothing is uploaded,' which is meaningful for a tool whose inputs may be URLs. It also discloses the response contents (per-specification pass/fail, applied/passed/failed counts, first failures with element and reason), which matters because there is no output schema. Not exhaustive on limits (e.g. size ceilings or runtime), but well beyond the annotation baseline.

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

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

Two sentences, front-loaded with the operation and result, then the usage trigger. The parenthetical IDS expansion earns its place by disambiguating an acronym, and there is no filler or repetition of the title.

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

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

Because there is no output schema, the description carries the return-value burden and does so at an appropriate level — structure and failure detail are stated. Inputs, locality, and purpose are all covered for a three-parameter tool. It leaves open how sibling validate_ifc differs and any practical limits on large IFC files, which keeps it short of a 5.

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

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

With 100% schema description coverage, the schema already documents all three parameters including accepted forms for ids and ifc and the maxFailures default. The description adds only an oblique reference to 'the first failures', which gestures at maxFailures without explaining its effect. Baseline 3 is the right ceiling when the schema does the heavy lifting.

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

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

States a specific verb+resource pair: check an IFC model against an IDS file, with the standard spelled out (buildingSMART IDS 1.0). It also names the return shape, so the agent knows what it gets back. It does not differentiate itself from the sibling validate_ifc, which is the only 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?

Gives a concrete trigger: 'Use it when the user has an .ids file, or exchange requirements to verify a delivery against.' That is a clear context for selection. It falls short of explicit exclusions or a routing rule versus validate_ifc, so an agent facing both siblings must still infer which one applies.

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