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

Annotations only declare the generic mutation profile (readOnlyHint false, idempotentHint false, destructiveHint false). The description adds substantial behavior: the GPU engine's 7 supported quantities, the warn-and-fall-back-to-WALL-HEAT-FLUX behavior for unsupported quantities, and the WALL HEAT FLUX vs NET HEAT FLUX portability trap. That is exactly the kind of context annotations cannot carry.

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-loads the core action and examples, then layers engine caveats in descending order of importance; every sentence carries operational weight. The trailing rule reference ('[bulc-mcp rules] OUT-005 — bulc_knowledge_search "<id>"') is cryptic filler that slightly blurs the end of an otherwise tight description.

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 3 params, no output schema and only generic annotations, the description covers the important unknowns: valid quantity names, engine compatibility, ID parameter mapping, and the CPU-vs-GPU naming hazard. It does not address what happens on duplicate additions (relevant given idempotentHint=false) or any confirmation/return behavior, leaving a small 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 100%, so the baseline is 3, but the description adds real meaning beyond the terse schema text: it enumerates which quantities go with spec_id (MASS FLUX, SURFACE DEPOSITION, MPUA_Z, CPUA_Z, AMPUA_Z) versus part_id (MPUA, CPUA, AMPUA) and constrains quantity to uppercase FDS 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?

States a specific verb ('Add') plus the exact resource ('animated boundary quantity (&BNDF)') with concrete examples (WALL TEMPERATURE, ADIABATIC SURFACE TEMPERATURE). An agent can immediately distinguish it from list_bndf and remove_bndf without opening a 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 clear selection rules for the parameters: spec_id for species quantities (with the list of valid names) and part_id for particle quantities. It also states the engine-constraint condition ('Any other quantity needs CPU FDS'). It stops short of explicitly contrasting with sibling tools, but for a create-style tool the guidance present 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?

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false) and the description is consistent with them, so no contradiction. The description adds useful semantic behavior (input_id may reference device IDs, other CTRL IDs, or CONSTANT; math functions with setpoint+trip_direction act as boolean gates), but says nothing about error handling for invalid function_type/parameter combinations, duplicate IDs, or required permissions.

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 action, then a compact catalogue of function types and input rules; for 25 function types and 17 parameters the density is justified and no sentence is filler. The one downside is that the run-on FUNCTION_TYPE enumeration is hard to parse and could be broken into lines, which keeps it just short of 5.

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 17-parameter, 25-variant creation tool with no output schema, the description covers the domain vocabulary well, and the absence of a return-value explanation is acceptable. However, it omits preconditions (must referenced devices/controls exist?), behavior on invalid combinations, and interaction with update_control, leaving real gaps for a tool of this complexity.

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%, giving a baseline of 3, and the description genuinely adds cross-parameter semantics the schema does not: it maps each function type to the parameters it consumes (DEADBAND -> setpoint+setpoint2+on_bound, PID -> target_value+gains, CUSTOM -> ramp_id, TIME_DELAY -> delay, X_OF_N -> n). This tells an agent which of the 17 params matter for a chosen function_type, exceeding individual property 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?

States a specific verb and resource ("Add a CTRL control logic element") and then enumerates the complete space of FUNCTION_TYPE variants with their dependent parameters, so an agent knows exactly what object class is being created and which configurations are valid. This makes it unmistakable against siblings such as add_device, add_vent, update_control, and remove_control.

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 only implied: the bulc-mcp rules pointer (DEVC-004, DEVC-006 -> bulc_knowledge_search "<id>") hints that rules should be consulted, and the operation is obviously the creation counterpart to update_control/remove_control, but the description never explicitly says when to prefer this tool, what preconditions must hold, or when not to use it. No explicit exclusion or alternative-routing guidance is given.

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 write/non-idempotent/non-destructive behavior, so the safety profile is covered. The description adds the DEVC-001/003/004 rule references pointing to bulc_knowledge_search, which hints at validation constraints — modest but real value. It does not state whether the call mutates existing devices, error behavior, or the non-idempotent nature beyond what annotations declare.

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 action and resource, followed by a compact enumeration of supported domains and one actionable geometry-selection rule. The trailing bulc rule-pointer is terse and useful. The opening sentence is dense but not redundant.

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 37-parameter creation tool with 100% schema coverage and no output schema, the description supplies the missing cross-cutting guidance (geometry parameter choice) and points to validation rules. Return values need not be explained without an output schema; remaining gaps (mutation semantics, error cases) are minor.

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 the schema documents all 37 parameters and the baseline is 3. The description goes beyond the schema by stating cross-parameter selection rules (xyz for point quantities vs xb for flow/HRR/layer/beam/statistics), which is genuinely useful guidance an agent could not derive from per-field descriptions alone.

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 ('Add') and resource ('measurement device (&DEVC)') and enumerates the domains it covers (point/region quantities, species, statistics, trip options, post-processing, aspiration, HVAC, particles). It is clearly a device-creation tool, but it does not differentiate itself from siblings such as add_heat_detector, add_smoke_detector, or add_thermocouple.

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?

'Provide xyz for point quantities or xb for flow/HRR/layer/beam/statistics' gives conditional guidance on which geometry parameter to supply. However, it offers no when-to-use guidance relative to the specialized sibling adders (detectors, thermocouples) and no exclusions or prerequisites, leaving tool selection 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?

Annotations already describe the safety profile (readOnly=false, destructive=false, idempotent=false), so the bar is lower. The description nonetheless adds a real behavioral trait: the tool creates a HOLE geometry that cuts through the wall, which is not derivable from the annotations, plus a pointer to rules EVAC-002/GEO-004.

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 front-load the purpose and mechanism, followed by a compact rules reference. Everything is relevant; the bracketed rule line is slightly cryptic but earns its place as a compliance pointer.

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 5-param mutating geometry tool with no output schema but full schema coverage and annotations, the description covers purpose, mechanism and params adequately. It still omits prerequisites (existing wall), the relationship to add_hole/add_window, and any note on reversibility.

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 schema already documents defaults for width, height and position. The description only restates 'wall obstacle ID and door position/size' at a high level, adding no syntax or range detail beyond the schema, which lands it at the baseline.

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 ('add a door opening in a wall') and the mechanism ('Creates a HOLE that cuts through the wall'), so an agent understands the effect. It stops short of naming the sibling it differs from (add_window, add_hole), so sibling differentiation is only implied.

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?

'Convenience tool' and 'Specify the wall obstacle ID and door position/size' hint at when to reach for it, and the rule reference signals a compliance step. But it never states when to prefer this over add_hole or add_window, nor any prerequisite (e.g. an existing wall), so guidance is implicit rather than explicit.

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 the mutation profile (readOnly=false, destructive=false, idempotent=false). The description adds that both ramp_points and growth auto-create and link a RAMP, which is useful side-effect context beyond the annotations, but it does not cover failure modes, permission needs, or reversibility.

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-loads the core action in the first sentence, then explains inputs compactly. The bracketed rules tag is a bit cryptic but functions as a compliance pointer; overall it is well-sized with little waste.

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 tool with annotations covering safety and a fully documented schema, the description supplies enough to call it correctly, including the two mutually exclusive curve paths and the RAMP side effect. No output schema exists, and none is implied as 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 the schema already documents every parameter, including the RAMP auto-generation on growth and ramp_points. The description mostly restates it (HRRPUA, XB location, curve options), so the 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?

States a specific verb+resource ('Add a fire source') and immediately clarifies the domain meaning of the key inputs (HRRPUA, XB). It does not explicitly name sibling alternatives such as update_fire or remove_fire, so it falls short of full sibling 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?

Gives conditional guidance for the time-varying case ('pass ramp_points OR growth') and points to the FIRE-001..003 rules via bulc_knowledge_search. However, it never states when to choose add_fire over update_fire/remove_fire, so tool-selection guidance is only 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?

Annotations already declare this is a non-read-only, non-idempotent, non-destructive, non-open-world mutation, so safety is covered. The description adds only that thickness is optional, plus a cryptic rule reference (GEN-003, GEO-007) whose behavior impact is unexplained; it does not say whether surf_ids are required for material assignment or what happens to overlapping slabs.

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 core sentence is tight and front-loaded, but the trailing "[bulc-mcp rules] GEN-003, GEO-007 — bulc_knowledge_search \"<id>\"" fragment is cryptic overhead that does not clearly help an agent invoke the tool.

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 an 8-parameter geometry-creation tool with no output schema and thin schema coverage, the description omits what is created from surf_ids, whether an id must be unique, and any project-state precondition. It is too sparse to fully guide a correct call.

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 only 38% (6 of 8 parameters undocumented). The description compensates for x_min/x_max/y_min/y_max and thickness, but leaves id, z, and especially surf_ids — likely the most consequential parameter — completely unexplained in both schema and 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 ("add a floor slab") and names the two key inputs (x/y range, thickness), so it is distinguishable from generic siblings like shape_add_box or add_obstacle. It is not fully differentiated from those overlapping geometry-creation siblings, which keeps it out of 5 territory.

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?

Calling itself a "convenience tool" hints that an alternative exists but never names it (e.g., add_obstacle or shape_add_box) or states when this should be preferred over them. There is also no mention of prerequisites such as an open project or document.

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 declare it is a non-read-only, non-destructive, non-idempotent write, and the description meaningfully adds *what* gets written — a small obstacle plus DEVC and PROP namelists in the FDS output — which is genuine behavioral context beyond the safety hints. It does not cover repeat-call effects or permissions, but for a local project mutation this is solid.

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?

Very short and front-loaded: the effect (convenience detector) precedes the FDS-emission detail, and the bulc rule pointer is compact. Every clause earns its place, though the rules line is somewhat cryptic without 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?

There is no output schema, and the description does not say what the call returns or how the created DEVC/PROP can be located afterward. Annotations carry the safety profile and the FDS-emission sentence covers the main side effect, leaving it adequate but not fully complete for a six-parameter mutation 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%, so the schema already documents all six parameters (x/y/z, id, rti, activation_temp) with units and defaults. The description adds no positional or value syntax 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?

States a specific verb+resource ('add a heat detector') and adds real scope detail — it is created as a small obstacle and emits DEVC+PROP in FDS output. This distinguishes it from the generic add_device sibling without requiring the schema to be opened, though it stops short of naming the alternatives.

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 word 'Convenience:' implies this is a shortcut over the generic add_device path, which gives an agent an implicit sense of when to reach for it. However, there is no explicit when/when-not guidance and no named alternative, so selection still requires 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?

Annotations already declare the full safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the mutation/idempotency facts are covered. The description adds that XB defines the hole volume, but omits the key behavioral fact of how the hole attaches to a parent obstacle (which object 'id' refers to).

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, front-loaded sentences that lead with the action and definition. The bracketed rule-reference footer is somewhat opaque but compact.

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 2-parameter additive tool with annotations covering the safety profile and 100% schema coverage, the core is present. However, the parent/child relationship implied by 'hole in an obstacle' and the meaning of 'id' are left unresolved, leaving a gap an agent must guess at.

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 documented in the schema, including the XB format and 6-item constraint. The description's 'XB defines the hole volume' merely restates the schema, and it does not resolve whether 'id' is the hole's identifier or the owning obstacle's id.

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 ('Add a hole') and clarifies what a hole is ('opening in an obstacle') in the FDS model, which distinguishes it from siblings like add_obstacle, add_vent, and remove_hole. It stops short of explicitly contrasting with those siblings.

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 when-to-use guidance, no prerequisites, and no named alternatives among the many add_* siblings. The only routing hint is a cryptic '[bulc-mcp rules] GEO-004, GEO-008 — bulc_knowledge_search' pointer, which requires external lookup rather than explaining usage.

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 disclose that this is a non-readonly, non-destructive, non-idempotent write, so the safety profile is covered. The description adds nothing beyond the purpose: it does not say what happens if the ID already exists (rejected vs overwritten), what validation applies, or what result is returned, all of which matter for a non-idempotent create.

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?

Very short and front-loaded: the purpose is in the first clause, before the bracketed metadata. The second sentence is terse but useful as a procedural pointer, so little is wasted, though the placeholder notation is opaque.

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 5-parameter create tool with no output schema, the definition plus full schema coverage and annotations is minimally sufficient to invoke it. It is nonetheless incomplete on duplicate-ID behavior, success/failure feedback, and the relationship to update_material/remove_material, which an agent would need in order to use it correctly in a workflow.

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% with units supplied inline (kg/m³, W/m·K, kJ/kg·K, emissivity range), so the schema carries the full burden. The description adds no additional parameter semantics, which is the expected baseline 3 when the schema is 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 pairs a specific verb with a specific resource ('Add a material definition (MATL)') and names the FDS namelist it maps to, so an agent immediately knows this creates a material object. It does not, however, differentiate itself from siblings such as add_material_from_library, update_material, or remove_material, which an agent must infer from names alone.

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 only guidance is a cryptic bracketed rule reference ('SURF-001 — bulc_knowledge_search "<id>"'), whose placeholder is ambiguous and which never states when to use add_material versus add_material_from_library or update_material. No conditions, prerequisites, or exclusions are 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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation profile is covered. The description adds useful domain context (the result is an FDS &MATL namelist) beyond the annotations. However, it is silent on what happens when the copy is repeated (idempotentHint=false suggests duplicates may accumulate) and gives no reversibility or naming-conflict guidance.

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 efficient sentence front-loads the action and result, with no filler. The appended bracketed rules line is terse and slightly cryptic (a placeholder '<id>' with no explanation of when to consult it), which keeps it just short of a 5.

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, and the description says nothing about the return value or the created object's identity, nor about duplicate-ID behavior. For a simple two-parameter creation tool with complete schema coverage this is adequate but leaves the post-call state 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 100%, so both parameters (id, library_id) are fully documented in the schema, including the defaulting behavior of id. The description adds no format or syntax detail beyond that. Baseline 3 is appropriate 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 and resource: 'Copy a material preset from the built-in library into the model as a &MATL.' The 'from the built-in library' qualifier distinguishes it from the sibling add_material, which presumably creates a custom material. It is clear without opening the schema, though it does not name the sibling explicitly.

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 statement of when to use this tool versus add_material or add_surface_from_library. The only routing hint is buried in the appended 'SURF-001 — bulc_knowledge_search' rules reference, which points at an unrelated knowledge tool rather than explaining tool selection. The library_id dependency is documented in the schema, not the description.

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 the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false), while the description adds substantial behavioral detail: it enumerates the DEVC, PROP, PART, SPEC and REAC entries automatically created and notes REAC alignment happens only when no reaction is set. This goes well beyond structured fields and helps predict side effects.

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 front-loaded with 'Convenience: add...' followed by one dense sentence, with no filler text. The long parenthetical enumerations of namelist fields hurt readability slightly, as bullet points would be clearer for an agent parsing the side effects.

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 an 11-parameter tool with no output schema, the description covers creation behavior and side effects well, including the important REAC alignment condition. It omits prerequisites such as needing an open project or existing simulation, but annotations and the schema cover the remaining safety and parameter details.

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 the baseline is 3; the description adds value by mapping parameters to the FDS namelist fields they populate (e.g., mass_flow_rate/flow_ramp_points into PROP, spec_id into SPEC) and mentioning the built-in fuel database. It does not restate every default, but adds conceptual 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?

States a specific verb 'add' and resource 'Lagrangian-particle virtual fuel nozzle', with a concrete example (hydrogen TPRD jet release). It distinguishes itself from generic siblings like add_prop/add_device by framing itself as a convenience that automatically builds the full nozzle setup, so an agent can tell it apart 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?

Usage is implied through 'Convenience' and the hydrogen TPRD jet-release example, which points to when this tool is appropriate. However, no explicit when-not conditions or named alternatives (e.g., manually using add_prop/add_device/add_species) are provided, leaving routing 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?

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so mutability and non-idempotence are covered. The description adds the coordinate ordering and metre units, plus a governance-rule pointer, but says nothing about duplicate-id behavior, overlap handling, mesh requirements, or what surf_ids do.

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 sentences, front-loaded with the action and immediately followed by the coordinate contract. The trailing rule reference is terse rather than bloated, though its unexplained angle-bracket syntax costs a bit of clarity.

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 geometry-creating mutation tool with no output schema, the essentials (verb, target model, coordinate format and units) are present, and annotations carry the safety profile. It still omits surf_ids semantics, uniqueness constraints, and any hint about prerequisites such as an existing mesh.

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 schema already documents id, xb and surf_ids, and the baseline is 3. The description's only added meaning is the unit ('in metres') and the axis ordering, which is marginal but slightly beyond the schema's 'Bounding box [x1,x2,y1,y2,z1,z2]'.

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 gives a specific verb and resource ('Add an obstacle (solid block) to the FDS model') and the parenthetical clarifies the geometric primitive, which helps separate it from wall/floor siblings. It does not, however, name or contrast with close alternatives such as update_obstacle, transform_obstacle, or shape_add_box.

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 when-to-use guidance and no stated alternatives, despite a crowded sibling set (update_obstacle, transform_obstacle, add_wall, add_floor, shape_add_box). The only routing hint is a cryptic tag pointing at bulc_knowledge_search, which is not explained.

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 annotations already declaring it a non-readonly, non-idempotent, non-destructive write, the description adds real context: presets seed defaults, any field can be overridden, and unlisted FDS 6.10.1 spray keys must be routed through `spray` using spr_upsert_spray_profile.prop names. It does not say what happens on a duplicate id, which is the main residual gap.

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 core action, then preset meanings, then the spray-routing rule. Dense but each sentence carries information; the trailing '[bulc-mcp rules] DEVC-009 …' fragment is somewhat cryptic but adds a pointer.

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 23-param mutation tool with no output schema, the description covers the two hardest concepts (preset semantics and spray-key routing). Missing only duplicate-id behavior and a note on units beyond what the schema already labels.

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 only 61% across 23 params, so the description must compensate and does: it enumerates the four quantity preset values with their meanings and explains the escape-hatch `spray` object. Many numeric physics fields (rti, beta, k_factor, bead_*) still rely on the schema's terse 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?

States a specific verb plus resource ('Add a &PROP device model') and immediately distinguishes it from siblings like update_prop/remove_prop by describing the preset-seeding behavior. An agent can tell what is created and how it is referenced (prop_id from devices).

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?

Explains the preset choice for quantity and points to bulc_knowledge_search for rules, which implies when the presets apply. However it never states when to reach for add_prop over add_device/add_heat_detector/add_sprinkler or when a preset vs full override is preferred, so alternatives are only 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?

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the mutation profile is covered. The description adds the [time, value] semantics of the payload, but says nothing about what happens when the ID already exists (duplicate vs overwrite) despite idempotentHint=false, which is the key behavioral question for this call.

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 core action and payload shape are front-loaded in two tight sentences with no filler. The trailing bracketed rule reference is cryptic and slightly disrupts an otherwise clean structure.

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 full schema coverage, no output schema and annotations covering the safety profile, the description supplies everything needed to invoke it. The unresolved FIRE-008 reference is a minor loose end rather than a blocking 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 100%, so both 'id' and 'points' are already documented, including the [time, value] pairing. The description restates the same pairing without adding format, units, ordering or monotonicity constraints, so it earns only the baseline.

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 ('Add a time ramp (RAMP) for time-dependent parameters') and clarifies the data shape. It does not explicitly distinguish itself from the siblings update_ramp and remove_ramp, leaving the add-vs-update boundary to inference.

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 statement of when to add a ramp versus updating or removing one, and no prerequisites such as needing an existing RAMP ID. The embedded '[bulc-mcp rules] FIRE-008' pointer is unexplained and does not function as actionable usage guidance.

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 declare the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds genuine context beyond that: verbatim emission, insertion point (before &TAIL), format validation, and the duplicate-namelist error. Only minor gaps (no statement about how entries are ordered/listed) keep it from 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?

Three tight sentences, front-loaded with what it does and where the line lands, followed by use cases and exclusions. Dense with useful detail, though the trailing rules-reference line is mild noise.

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?

A single-parameter mutation tool with no output schema is adequately covered: usage conditions, format rules, placement, and error behavior are all present. The remaining gap is lifecycle behavior (ordering of multiple raw lines, interaction with removal) which is minor for a tool this scoped.

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 gives an example, so baseline is 3. The description adds a real constraint not in the schema ('Must start with & and end with /') plus two more concrete examples, which meaningfully improves correct invocation.

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 (add) and resource (raw namelist line), plus the exact placement semantics ('emitted verbatim just before &TAIL'). An agent can distinguish it from siblings like list_raw_namelists and remove_raw_namelist, and the examples of what a namelist line looks like remove all 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?

Explicitly states when to use it ('settings with no GUI dialog') and when not to ('Use the dedicated tools for anything the GUI does model' with the full list of modeled namelists). It even names the failure condition for misuse (a duplicate namelist is an FDS error), so routing 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?

Annotations already declare readOnlyHint=false, non-destructive and non-idempotent, so the safety profile is covered structurally. The description adds nothing about what the write affects, whether duplicates conflict, or what the ASET-001/ASET-004/OUT-002 rules require — it merely cites rule IDs that are meaningless without another lookup.

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 sentences, front-loaded with the action, with no filler. The bracketed rules line is terse but is an unexplained pointer rather than clearly earning 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 an 8-parameter output-writing tool with no output schema, the schema and annotations carry most of the load, so the description is minimally sufficient. However, the cryptic rule IDs and the absence of any relationship to update_slcf/remove_slcf leave a real gap for correct 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 100%, so the schema already documents id, quantity, plane positions, vector, spec_id and cell_centered. The description only echoes 'quantity and plane position', adding no format, default, or constraint detail beyond the schema, which is the expected baseline when schema coverage is this high.

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 ("Add a slice file output (SLCF)") plus the two things to supply (quantity, plane position), which is enough to distinguish the action. It does not differentiate from the sibling mutation tools update_slcf / remove_slcf, 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?

There is no statement of when to use this versus update_slcf, remove_slcf, list_slcf, or output_add_tenability_slices, nor any prerequisite or exclusion. The only vaguely directional text is the bulc rule reference, which tells the agent to consult knowledge but not when this tool is the right choice.

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 cover the safety profile (readOnly=false, destructive=false, idempotent=false), and the description adds real behavior beyond them: the detector is physically instantiated as an obstacle with an FDS override, and it emits DEVC+PROP namelists into the FDS deck. A caveat would help (e.g. that calling twice with the same id is not idempotent), but the extra context is substantive.

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, front-loaded sentences with zero filler: what it does, then what it produces. The bracketed rules tag is cryptic but compact and does point to a concrete follow-up tool.

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, and the description does cover the generated FDS output and a rule lookup path, which is adequate. It still omits whether an open project is required and what the tool returns on success, gaps that matter for an 8-parameter mutation 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 every parameter including the alpha/beta defaults is documented there, so baseline 3 applies. The description contributes nothing about coordinate defaults (z = ceiling height) or the id naming convention beyond what the schema already says.

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 ('add a smoke detector') and clarifies the implementation ('as a small obstacle with FDS override') plus the side effect ('Generates DEVC+PROP in FDS output'). This implicitly distinguishes it from add_heat_detector, add_thermocouple, and add_device, though it never names those siblings explicitly.

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?

'Convenience:' signals it is a shortcut over generic device/obstacle creation, and the rule tag points the agent at bulc_knowledge_search for DEVC-001/DEVC-009. However there is no explicit statement of when to pick this over add_device or add_heat_detector, and no prerequisites (e.g. whether it is safe alongside add_obstacle).

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 that this is a non-read-only, non-destructive, non-idempotent mutation. The description adds no further behavioral detail beyond the vague qualifier "tracked" — it does not explain duplicate behavior, required preconditions, or what state is created.

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 wasted words. Its extreme brevity borders on under-specification, but it is structurally clean and concise.

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 annotations cover the safety profile and the schema fully covers both required parameters, so basic invocation context exists. However, the description omits domain context such as when a species should be added, how it relates to remove_species, and what "tracked" implies in the simulation setup.

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 fully documented in the schema. The description adds no parameter meaning beyond what is already present, which is the expected baseline 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?

The description states a clear verb ("Add") and resource ("tracked species"), making the basic action unambiguous. It does not differentiate this tool from other add_* siblings such as add_material or add_surface, but the core purpose 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 description gives no when-to-use guidance, no prerequisites, and no explicit alternatives such as remove_species. It only names the action, leaving the agent to infer 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?

Annotations only state the generic write/non-idempotent/non-destructive profile; the description goes well beyond that by disclosing the three namelists created, the FDS validation failure mode (ERROR 238 for K-alone/pressure-alone), the override precedence rule (spray/particle override any other &PROP/&PART key for this head), the upright-heads-spray-downward quirk, and the activation semantics. This is exactly the extra behavioral context the annotations cannot carry.

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 convenience statement and creation summary are front-loaded, then detail follows. It is dense and sentence-heavy (long compound clauses on profiles and overrides), but nearly every sentence carries load – error codes, defaults, and precedence rules are all actionable.

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 17 parameters, nested objects, and no output schema, the description does the heavy lifting well: it explains creation, flow specification, override behavior, and activation. It omits the return value (acceptable with no output schema) and never addresses the overlapping sprinkler-head siblings, which is the main 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 coverage is 100%, so the baseline would be 3, but the description adds real meaning: the Q=K√p derivation relationship, the mutual-exclusion constraint between k_factor/pressure and flow_rate, the default profile versus profile_id selection, and how spray/particle merge with other keys. It stops short of documenting units for xyz or the activation sub-fields in narrative form.

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 and resource: it 'add[s] a complete sprinkler head' and enumerates exactly what is created (DEVC + PROP with QUANTITY=SPRINKLER LINK TEMPERATURE + water-droplet PART). However, it never distinguishes itself from the sibling spr_add_sprinkler_head / spr_update_sprinkler_head, so an agent could not tell from the text alone why it should prefer one over the other.

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 flow rules (supply k_factor+operating_pressure, or flow_rate, and notes K-alone or pressure-alone is rejected by FDS with ERROR 238) and points to spr_upsert_spray_profile as the source for alternate profiles and prop/part keys. There is no explicit 'use this instead of X when...' statement, and no prerequisites (e.g. project must be open) are given.

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=false, destructiveHint=false and idempotentHint=false, so the mutation profile is covered. The description adds domain framing (heat transfer, burn-away) but says nothing about what happens on an ID collision with an existing surface or how the new surface relates to assignment via assign_surface — gaps the annotations do not fill.

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, front-loaded with the core action, with no filler. The rule-reference fragment ('[bulc-mcp rules] SURF-001, VENT-005 — bulc_knowledge_search "<id>"') is terse and slightly cryptic, but it is compact and actionable.

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 31-parameter, nested-object creation tool with no output schema, the description adequately conveys the tool's role, and the schema covers all inputs. It still leaves the sibling workflow implicit — nothing tells the agent that materials must pre-exist or that the surface must be attached with assign_surface — so it is strong but not exhaustive.

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% across 31 parameters with enums and nested objects fully documented, so the schema carries the load. The description names the broad parameter groups (layers, burning, thermal BC, injection) but adds no syntax or constraint detail beyond what the schema already states. 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?

Clear specific verb+resource: creates an FDS &SURF surface with layers, burning behaviour, thermal BCs and injection. It also conveys the downstream effect (walls get heat transfer, can burn away). It never names update_surface/remove_surface/list_surfaces to differentiate the create path from its siblings, so it stops 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?

There is no explicit when-to-use / when-not-to-use statement and no named alternatives (e.g., add_surface_from_library, update_surface). The only guidance is an implied prerequisite — consult bulc rules SURF-001 and VENT-005 via bulc_knowledge_search before adding — which is useful but partial.

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 declare readOnlyHint=false and destructiveHint=false but say nothing about side effects. The description usefully discloses that this pulls in dependent materials ('pulling in any materials it needs'), which is real behavioral information beyond the structured fields. It stops short of saying what happens if the requested ID already exists or whether the copied materials are shared or duplicated.

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 core action is front-loaded in a single efficient sentence with no filler. The appended '[bulc-mcp rules]' fragment is terse to the point of being cryptic, slightly weakening the structure, but nothing is wasted.

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 write operation with no output schema, the description covers the essential outcome (a &SURF is created plus its materials), which is adequate. It leaves open collision handling on the target ID and the exact source of valid library IDs beyond a GUI pointer, so it is complete enough to attempt the call but not to predict failures.

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% with only two parameters ('library_id' and optional 'id'), so the schema already documents both, including the default behavior of 'id'. The description adds no syntax, format, or sourcing detail beyond what the schema states, 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?

The description uses a concrete verb+resource: 'Copy a surface preset from the built-in library into the model as a &SURF,' which is materially distinct from add_surface (manual creation) and add_material_from_library (different resource). It does not explicitly name or route against those siblings, so an agent must infer the distinction from the phrase 'from library.'

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 explicit statement of when to choose this over add_surface or assign_surface. The trailing fragment '[bulc-mcp rules] SURF-001 — bulc_knowledge_search "<id>"' implies a rule-compliance step but is opaque enough that an agent cannot tell what precondition it must satisfy before calling.

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=false, idempotentHint=false, destructiveHint=false, and openWorldHint=false, so the mutation profile is covered. The description adds genuinely new context beyond that: the thermocouple is realized as a small obstacle with an FDS override and produces a DEVC in FDS output, which tells the agent about side effects on the model tree.

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 compact sentences front-load the core purpose and the side effect, with no padding. The bracketed rule pointer is terse, though its 'DEVC-001 — bulc_knowledge_search "<id>"' form is cryptic without surrounding explanation.

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 6-parameter mutation tool with no output schema and no annotations gaps, the description covers the essential mechanics (obstacle + DEVC). It stops short of covering prerequisites (e.g., whether a surface or FDS override context is required) and sibling differentiation, which is the main remaining 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 100%, so all six parameters (x/y/z, id, emissivity, bead_diameter) carry their own descriptions including units and defaults. The description mentions no parameter semantics at all, so the baseline 3 applies — 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?

The description states a clear verb+resource ('add a thermocouple') and goes further by naming the implementation approach ('as a small obstacle with FDS override') and its output effect ('Generates DEVC in FDS output'). It does not, however, distinguish itself from device-adjacent siblings such as add_device, add_heat_detector, or add_smoke_detector, leaving the agent to infer the boundary.

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 explicit when-to-use or when-not-to-use guidance. The DEVC-001 rule pointer to bulc_knowledge_search hints at a compliance step but does not state when this tool should be chosen over add_device or add_heat_detector, so routing between siblings is 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?

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the mutation profile is covered. The description adds the rule-id provenance pointer, which is genuinely extra behavioral context, but it omits what happens on a duplicate id, whether surf_id must reference an existing surface, and whether mass_flux and dynamic_pressure are mutually exclusive.

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 sentences with the core purpose front-loaded, followed by a compact rule-reference line. Nothing is padded, though the bracketed rule pointer is terse enough to be slightly cryptic without 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?

For a 5-parameter mutation with no output schema and no annotations gap, the description is minimally adequate but leaves out prerequisites (does surf_id need to exist?), the relationship between mass_flux and dynamic_pressure, and the effect of adding a vent on the FDS deck.

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 parameters including mass_flux and dynamic_pressure are already documented in the schema. The description only adds that XB defines the vent surface, which is a minor restatement of the schema's '[x1,x2,y1,y2,z1,z2]' hint. Baseline 3 applies 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?

States a specific verb+resource ('Add a vent (boundary patch)') and clarifies that XB defines the vent surface, which distinguishes it from sibling mutators like add_bndf and add_surface. Sibling differentiation is implicit (contrast with list_vents/update_vent is obvious from the verb), but it does not explicitly say what makes a vent different from a generic boundary.

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 bulc rule references (EVAC-002, VENT-002, VENT-004) plus the bulc_knowledge_search pointer imply the agent should consult rules before adding a vent, which is useful procedural context. However, there is no explicit when-to-use vs update_vent, remove_vent, or add_bndf guidance, so usage is only 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the safety profile is covered. The description adds real behavioral context by noting the automatic OBST bounding-box computation and that points live on the floor plane, but says nothing about duplicate ids or what happens on re-add despite idempotentHint=false.

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 purpose and defining inputs in one efficient sentence, followed by a short behavioral note. The appended rules/reference line is compact, though it is closer to metadata than to tool documentation.

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?

A 7-parameter mutation tool with no output schema and annotations that only cover the safety profile: the description gives the core geometry semantics but leaves surf_ids undocumented and doesn't state the effect of a duplicate id. Adequate but with 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 86%, so the schema already documents most parameters, including the height/thickness defaults. The description contributes only the floor-plane coordinate interpretation of start/end; undocumented 'surf_ids' and the meaning of z_base get no help from the description. Baseline 3 fits.

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 ('add a wall') and names the defining inputs (start, end, height, thickness) plus the automatic OBST bounding-box calculation. It is clear what the tool does, but it never distinguishes itself from close siblings like add_obstacle or draw_add_story, which an agent building geometry would reasonably compare against.

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 when-to-use or when-not-to-use guidance; nothing tells the agent why to pick add_wall over add_obstacle or the draw_* wall tools. The bulc rules line is a compliance pointer to bulc_knowledge_search, not guidance for selecting 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?

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), lowering the disclosure bar. The description adds only that this cuts an opening into an existing wall plus a rule-check pointer; it does not explain whether the operation is undoable, whether the window must fit the wall bounds, or what the call returns. This is adequate but thin.

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, front-loaded sentences with no filler. The bracketed rules reference is cryptic and slightly cryptic to parse, which keeps it just short of ideal, but the core purpose is stated 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?

With a 6-parameter mutation tool, full schema coverage, no output schema, and annotations covering safety, the definition is workable but leaves gaps: it says nothing about what the tool does to the wall geometry on success, failure conditions, or how it relates to the draw_set_window_params sibling that configures window parameters.

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%, with defaults documented per parameter (width 1.2m, height 1.2m, position 0.5, sill_height 0.9m), so the schema carries the load. The description adds nothing beyond the sill-height concept, which is the minimum-viable baseline.

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 concrete verb and resource ('add a window opening in a wall') and explicitly contrasts itself with the sibling add_door, noting the sill-height difference. That contrast lets an agent distinguish it from the similarly-named add_door/add_hole 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?

Calling itself a 'convenience tool' and pointing to rule GEO-004 via bulc_knowledge_search implies context of use, but there is no explicit when-to-use vs add_door, add_hole, or the draw_add_story / draw_set_window_params family, nor any stated preconditions such as needing an existing wall.

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 read-only/idempotent/non-destructive/non-open-world, so the safety profile is covered. The description adds meaningful behavior beyond that: the file is read on this PC only (local, no uploads), the needsVision fallback for rasters/outlined PDFs, and the returned artifacts (candidateId, summary, questions DRW-001…003). It stops short of describing pagination limits on show output beyond the schema's limit description.

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 core verb and resource, then progressively narrower detail (formats → extraction list → return artifacts → fallback → show values → read-only). It is dense and readable, though the single run-on sentence packs a lot, and the bracketed 'bulc-mcp rules' fragment is terse enough to be ambiguous about its purpose.

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 carries the return-value burden — and it does, naming candidateId, summary, and confirmation questions (DRW-001…003). With 7 parameters including a nested options object, some option semantics rely on the schema, but the tool's overall contract is sufficiently complete for correct 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 coverage is 57%, so the schema documents roughly half the params. The description adds some value: it enumerates show values (walls | openings | columns | rooms | levels | layers) and mentions layer-role and scale inputs conceptually. But it does not clarify ids, or most nested options (wallThicknessRange, minWallLength, page) beyond what the schema already states, leaving the undocumented half partially 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?

States a specific verb (Read/recognise) and resource (architectural floor plan) with a precise enumeration of what is extracted: units/scale, layer roles, wall centrelines, doors, windows, columns, stairs, rooms. It distinguishes itself from the sibling spr_analyze_drawing (sprinkler) and names arch_import_floorplan_report as the downstream step, so an agent can place it without opening other 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?

Gives clear usage context: use it for .dxf/.dwg/.pdf/image plans, and explicitly routes the agent when images/outlined PDFs return needsVision — 'read the picture yourself and call arch_import_floorplan_report.' It also notes the re-analysis path via candidateId. It does not spell out when NOT to use it vs. other intake tools, so it falls short of a full 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 declare destructive/non-idempotent/non-readonly, and the description adds substantial context beyond them: the operation is a single undo step, dryRun defaults to TRUE, mode=replace removes geometry from a prior import with the same idPrefix, and openings that cannot be placed are listed in warnings. This is exactly the extra behavioral detail an agent needs.

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?

Dense but front-loaded, leading with the outcome (create building in one undo step) before the spec details. The long inline building-spec sentence is information-heavy, though every clause maps to a real 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?

For a 13-parameter, nested-object, mutation tool with no output schema, the description covers source selection, defaults, dry-run workflow, id prefixing, and warnings. It omits transform/origin placement guidance, which lives only in the schema, but the overall coverage is strong given annotations carry the safety profile.

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 already high (85%), but the description still adds meaning: wall:n is 1-based in building.walls order, story defaults to the current story with z = zMin and wall height = story height, and mode append/replace semantics. It reinforces rather than merely restates 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?

States a specific verb and resource ("Create the building on one story") and enumerates exactly what is produced: walls as axis-aligned obstacles, doors/windows as named holes, columns, slabs. It clearly differentiates itself from arch_analyze_drawing, which it names as the source.

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 workflow: consume candidateId from arch_analyze_drawing or supply a hand-written building spec, run dryRun (default TRUE), confirm with the user, then re-call with dryRun:false. It does not explicitly compare against the sibling arch_import_floorplan_report, so it stops short of 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 declare destructiveHint=true, idempotentHint=false, readOnlyHint=false. The description adds genuinely useful behavior beyond that: dryRun defaults to TRUE, the app converts the report with fixed rules (snap to H/V, y-flip, lower-left origin), and no AI key is required. It does not spell out what 'replace' destroys or auth requirements, so it is 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?

Dense but front-loaded, leading with the purpose and activation condition before the report schema. It is long and run-on in places, but nearly every clause (coordinate origin, y direction, dryRun default, conversion rules) carries information an agent needs, so little is wasted.

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 an 11-param mutation tool with nested objects and no output schema, the description covers the hard parts: the report contract, coordinate conventions, dry-run safety, conversion semantics, and placement defaults. Gaps remain around the append/replace mode effect and story/zBase implications, but the definition is largely self-sufficient.

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 64% schema coverage, the description meaningfully compensates: it fully specifies the required 'report' payload (fields, units, coordinate convention, splitting at corners, what to skip), the image aspect-ratio param, and the transform origin/target/mirrorY semantics. A few params (mode, story, zBase, idPrefix) get no description-level elaboration.

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 ('Build walls / doors / windows from YOUR reading of a floor-plan picture') and immediately names the trigger ('use when arch_analyze_drawing says needsVision'). It also ties itself to the sibling arch_import_building ('creates the same objects as arch_import_building'), so an agent can distinguish it 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 an explicit activation condition ('use when arch_analyze_drawing says needsVision') and clarifies the app needs no AI key, which frames the division of labour with the vision path. It stops short of an explicit when-not (e.g., when to prefer arch_import_building), but the routing context is clear.

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 cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false); the description goes beyond them by disclosing the faces-scoping semantics and the exact SURF_ID6 axis ordering. It still doesn't say whether an existing assignment is overwritten, but it adds meaningful behavioral context.

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, front-loaded with the core action and scoping rule; the only slight clutter is the inline rule-ID citation.

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 4-parameter mutation tool with no output schema, the description covers target types and face scoping adequately; only the overwrite/return behavior is 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%, and the description's face-order note ('SURF_ID6 order -X,+X,-Y,+Y,-Z,+Z') largely restates the 'faces' property description. Baseline 3 applies since the schema already carries the parameter detail.

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+resource with explicit target set: 'Assign a surface (SURF_ID) to an obstacle, vent or geometry.' This separates it from sibling creators like add_surface/update_surface, though no sibling is named 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?

It explains the scoping behavior (whole object vs. selected faces) but never states when to prefer this tool over alternatives such as update_surface or set_bndf. The bulc-mcp rule citation points to further reading, which is a weak form of guidance rather than an explicit when/when-not.

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 say the tool is a non-readonly, non-destructive mutation; the description goes far beyond by disclosing the refinement rules, the ordered budget-relaxation behavior (curvature, buffer, gap_cells, then min_cell) with reporting of changes, the refusal conditions for invalid decks, and the automatic MM2 + block-CG v2 switch at a 1:4 ratio. These are exactly the behavioral traits that change how an agent should call and then validate the 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?

Front-loaded with the purpose and the sibling comparison before moving into mechanics; every sentence carries substantive information and there is no filler. It is dense and long, with the engine-constraint enumeration reading more like reference material than selection guidance, which keeps it just under top marks.

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 tool with no output schema, the description supplies the missing pieces: what it produces, what triggers refusal, how it self-reports budget-driven changes, and how to verify the result via list_meshes. Nothing an agent needs to call it safely and correctly is 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 coverage is 100%, so baseline is 3. The description still adds meaning the schema does not: that cell size follows gap/gap_cells in narrow gaps, that min_cell is applied to the GEOM surface band, and how the params interact with the 2^k snapping and 2:1 level-change constraint.

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 ('Build a cut-cell multi-mesh deck from GEOM triangulated shapes') and immediately distinguishes itself from its closest sibling by noting that with no GEOM it is identical to auto_multimesh. An agent can route between the two 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?

Gives clear conditions: use it when the deck has GEOM shapes, and the no-GEOM case is explicitly delegated to auto_multimesh. It also names the verification step ('Verify with list_meshes') and states the deck is refused if gapped/overlapping/misaligned. It stops short of covering other mesh siblings (set_meshes, merge_meshes, auto_fit_mesh), so it is clear context rather than exhaustive when/when-not guidance.

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 annotations only say readOnlyHint=false, idempotentHint=false, destructiveHint=false, which tells the agent almost nothing about consequences. The description adds the crucial disclosure that any multi-mesh deck is reset to a single mesh, plus a warning glyph, which the annotations fail to convey. I read this as an expansion of behavior rather than a contradiction, since the reset alters mesh topology rather than deleting user objects, but the tension with destructiveHint=false is real.

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 core sentence is front-loaded and the warning plus alternative follow in the right order with no filler. The two bracketed [bulc-mcp] rule-ID lines are terse metadata that slightly clutter the definition, but they do point to bulc_knowledge_search for detail.

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, no-output-schema tool this covers the essentials: what is recomputed, the destructive side effect, and the sibling to use instead. It stops short of stating prerequisites (e.g., behavior with no obstacles present) or the units/limits of the fit, which is the remaining 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 100% and both margin parameters carry their own descriptions and defaults, so the baseline is 3. The description only alludes to 'plus margin' without explaining how margin_xy and margin_z differ or how they affect the fit, so it adds little 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?

Specific verb+resource with scope: it fits the mesh domain to the obstacle bounding box and recomputes NI/NJ/NK while preserving cell size. This distinguishes it cleanly from siblings like set_meshes, auto_multimesh, and set_mesh_cell_size. An agent can tell what it does 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 names explicit alternatives and the condition that selects them: use set_meshes / auto_multimesh to keep or build a multi-mesh deck. That is real routing guidance. It doesn't distinguish itself from auto_cutcell_mesh or slice_mesh/merge_meshes, so 4 rather than 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 flag destructive/non-idempotent, but the description adds substantial behavior beyond them: an invalid deck is 'refused, not committed', the domain may grow to a multiple of the coarsest cell with OPEN vents following, and a 1:4+ ratio silently switches the engine to MM2 storage plus composite block-CG v2. That is exactly the side-effect detail an agent needs.

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 what-is-built sentence is front-loaded before the constraints, so the important part lands first. It is dense and long with parentheticals, and the min_cell x 2^k quantisation is stated twice, but the length is largely justified by the complexity of the operation.

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 destructive, non-idempotent mesh generator with no output schema, the description covers inputs' effect, refusal behavior, domain growth, engine side effects, and a verification step. An agent has everything needed to call it and interpret the outcome.

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 the schema already documents the 'rounded DOWN to min_cell x 2^k' rule that the description restates. The extra engine-constraint ladder (k in 1,2,4,8,16) gives marginal added meaning, so the 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?

The opening sentence states a specific verb+resource ('Build a multi-mesh deck from the OBSTRUCTION geometry') and the algorithm detail makes the tool unmistakable. It never explicitly contrasts itself with the closely related siblings (auto_cutcell_mesh, auto_fit_mesh, set_meshes), so the sibling-differentiation half of the top criterion is only implied.

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 description ('Build a multi-mesh deck...') and one follow-up alternative is named ('Verify the result with list_meshes'). However, there is no guidance on when to prefer this over auto_cutcell_mesh, auto_fit_mesh, or set_meshes, and no stated prerequisites or 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so safety is covered. The description adds genuine behavioral context: it is deterministic, emits findings with rule ids, and lists the full validation coverage. The 4 MB cap is in the schema, and return format/pagination is not described, 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?

Purpose and the how-to-invoke guidance are front-loaded, and the dense rule list earns its place by disclosing validation coverage. Slightly verbose, and the trailing Korean sentence duplicates the purpose line, costing a point.

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, but the description conveys the shape of the result (findings tagged with rule ids, severity filter) and all required invocation context. Safety is fully covered by annotations. Adequately complete for a read-only checker.

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 the baseline is 3. The description restates the three input modes rather than adding syntax or precedence details beyond the schema, and the min_severity filtering is only described in the schema. Little added meaning over structured fields.

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 (check) and resource (FDS 6.10.1 deck) with clear scope: deterministic validation with rule ids. It enumerates concrete checks and explicitly distinguishes itself from validate_project. An agent can tell exactly what it does 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?

Specifies the three invocation modes (deck_text, local .fds path, from_app=true) and names the sibling validate_project with the differentiating condition (which also checks app-side state). Clear context for choosing it, though it lacks explicit 'when-not-to-use' exclusions beyond the validate_project complement.

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, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description's additions (identity verification, snapshot comparison, live-vs-bundled state) describe what is inspected rather than behavioral traits like side effects, permissions, or rate limits, so it sits at the adequate baseline for an annotated read-only 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?

Front-loaded with the verb and the enumerated checks, followed by the actionable call-first directive. The five-clause list is dense and the trailing Korean sentence duplicates the preceding English content, which is minor waste but no real bloat.

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, so the description helps by enumerating the states being reported (reachability, identity, tool count, snapshot match, live-vs-bundled). It does not describe the actual response shape or field names, which is the one remaining gap for a schema-less diagnostic 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?

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to clarify beyond confirming the call is argument-free.

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 ('Check') and lays out precisely what is verified: app running/reachable via the local bridge, identity of the responder, tool count, snapshot match, and live-vs-bundled tool list. No sibling tool performs this diagnostic, so the agent can distinguish it immediately.

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 explicit invocation timing: 'Call this first, and again whenever an app tool fails.' This is clear routing guidance with a concrete trigger. It stops short of naming an alternative or a when-not condition, but no alternative exists among the 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?

Annotations already set readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds substantial context beyond those: it reads files locally and never uploads, classifies from specific file features (extension, name, DXF layers, PDF fonts, ZIP contents, IFC entities), never returns text inside the drawing, and discloses that extract_geometry returns wall centre-lines. No contradiction with annotations.

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 front-loaded with the key purpose and usage in the first sentence, and most sentences carry useful technical detail. It is somewhat long, and the final Korean sentence repeats information already stated in English, which slightly dilutes conciseness without causing confusion.

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 full burden of explaining return values and does so clearly: it returns the playbook, questions to ask, tool sequence, and optional wall centre-line candidates. It also covers file formats, classification criteria, and privacy behavior, leaving no critical gap for an agent to invoke 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 description coverage is 100%, so the schema already documents all six parameters. The description reinforces 'Pass the ABSOLUTE local path' and adds a fallback context for extract_geometry, but does not meaningfully extend most parameters beyond what the schema provides. 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?

The description states a specific verb and resource: it classifies a drawing file and returns a playbook, questions, and a tool sequence. It explicitly positions itself as the 'first step' for any drawing, which distinguishes it from downstream siblings like arch_analyze_drawing and spr_analyze_drawing. An agent can select it without opening other 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 opening phrase 'First step for any drawing the user gives' gives explicit usage context, and the description names the downstream tools to use for each classification outcome (architectural plans → arch_analyze_drawing / arch_import_building, piping → spr_analyze_drawing / spr_import_network). This effectively routes the agent to the correct alternative after intake.

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 (readOnly, idempotent, non-destructive, non-open-world), and the description adds value beyond them by disclosing the return content (names, descriptions, full input schemas) and the compact-profile follow-up contract with bulc_call. Pagination/rate behavior is left to the schema's limit field.

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?

Purpose is front-loaded in the first clause, followed by the return description and the category list, which is long but genuinely load-bearing since it defines the accepted category values. The trailing Korean sentence is redundant for English readers but adds language coverage.

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 discovery tool with full schema coverage, the description supplies purpose, the category vocabulary, and the follow-up call pattern. No output schema exists but the description states what is returned. Only the relationship to sibling discovery tools is 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 the baseline is 3; the description earns above that by enumerating the full category taxonomy (project, arch, geometry, fire, ..., shape) even though the 'category' parameter has no schema enum, effectively supplying the missing value set. It also gives bilingual keyword examples implicitly via the Korean sentence.

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 precise verb+resource: 'Find BULC app tools by keyword (Korean or English) or category' and declares the return payload (names, descriptions, full input schemas). As a meta-discovery tool it is unmistakably distinct from every concrete sibling (shape_*, evac_*, spr_*, etc.).

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?

Clear context for invocation (keyword or category lookup) and an explicit next step: 'In the compact profile, call the tool you found with bulc_call.' It does not, however, distinguish itself from other discovery siblings such as bulc_knowledge_search or bulc_get_rules, so there is no when-not guidance.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact not in the annotations ('Works without the app'), but says nothing about result ranking, pagination beyond the schema's limit, or how the confidence tiers affect output.

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?

Purpose and filters are front-loaded in the first sentence, and the usage hint follows immediately. The trailing Korean sentence duplicates the first clause, which is a small redundancy, but the whole thing stays short and skimmable.

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-required-parameter list tool with annotations covering safety, the description is largely sufficient: it covers filters, timing, and offline availability. With no output schema, it could have described the summary vs full return shapes, which is the only material 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 coverage is 89% (baseline 3), but the description adds real value: it maps the ambiguous 'applies_to' parameter to 'class', names 'confidence' as a valid filter (that property has only an enum and no schema description), and pairs two filters in a worked example. That goes beyond restating 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?

States a specific verb and resource ('List modelling rules') plus the filtering dimensions, so the agent knows exactly what it returns. It does not name sibling tools (e.g. bulc_knowledge_search, get_conventions, bulc_check_deck) to sharpen the boundary, so it stops 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?

Gives explicit timing ('Use before a phase of work') with a concrete example filter combination (domain=sprinkler, min_severity=warning) and a downstream behavior ('quote rule ids when explaining'). No when-not-to-use or explicit alternative is offered, so it is clear context rather than full routing guidance.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one piece of genuine behavioral context — 'Works without the app' (no live project connection required) — but says nothing about result format or ranking, so it is modest added value against an already-rich annotation set.

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 core verb and scope, and each listed content kind is informative rather than filler. The trailing Korean gloss restates part of the first sentence and is mildly redundant, but overall the text is dense 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 4-parameter search tool with no output schema, the description supplies the content taxonomy and query formats an agent needs, and notes it works standalone. It does not describe the shape of returned results (fields, ranking, or how 'limit' interacts with kinds/domain filters), which is the main remaining 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 coverage is 100%, so the baseline is 3. The description goes beyond the schema's generic 'Rule id, class name, FDS key, error number or free text' by giving concrete literal formats ('FIRE-001', 'Mesh', 'MESH.IJK', 'ERROR 314') and confirming bilingual Korean/English queries — this meaningfully helps the agent construct a correct query.

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 (search the bundled BULC knowledge pack) and enumerates exactly what is searchable — rules, mistakes, ontology classes, playbook steps, glossary, FDS keys and errors. An agent can tell it is the retrieval tool. It does not explicitly distinguish itself from nearby siblings like bulc_get_rules or bulc_find_tools, so it stops 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?

It tells the agent what to pass (rule id, class, FDS key, error, or free text in ko/en) and that it 'works without the app', which implies offline retrieval. However it never states when to prefer this over alternatives such as bulc_get_rules or get_conventions, so usage is inferred 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 declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds useful context beyond that: the exact formula used, that IJK counts are constrained to factors of 2/3/5 for FFT-solver friendliness, and that it works without the app.

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 core computation and appropriately sized for a numerically non-trivial tool. The formula is dense but earns its place; the trailing Korean sentence and rule codes are marginally redundant but brief.

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 burden and does so well, enumerating the outputs (cell sizes, per-axis IJK, resulting cells, total cell count). The only gap is not naming when to use this versus the other mesh tools.

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 real meaning: it explains that quality maps to D*/dx = 4/10/16 (coarse/moderate/fine) and that domain_xb drives the IJK proposal. That clarifies the enum's semantics beyond the schema's bare labels.

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: it computes cell-size advice from the design fire size, via the characteristic fire diameter D* and the D*/dx targets, and optionally proposes IJK per axis and total cell count. This distinguishes it clearly from siblings like auto_fit_mesh, set_mesh_cell_size and auto_multimesh, which manipulate mesh objects rather than advise on sizing.

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 content ('Cell-size advice from the fire size', 'Works without the app'), signalling a pre-simulation advisory call that does not require the running app. However, it never states when to prefer this over auto_fit_mesh or when to supply cell_size vs quality, and no explicit alternative is named.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: it 'works without the app' (or against a bundled snapshot) and returns findings plus a playbook to follow — details an agent cannot get from the annotations.

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 action and its timing before the exhaustive rule enumeration, which is dense but load-bearing for understanding what is checked. Slight deduction for the very long rule list and a redundant Korean restatement of the opening 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?

No output schema exists, and the description compensates by saying it returns findings with rule ids and a playbook. Combined with offline-mode disclosure and step-format examples, an agent has what it needs; minor gaps remain around error behavior for unrecognized tool names and whether findings are advisory or blocking.

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. The description goes beyond the schema by spelling out the accepted step formats with a worked example ('add_fire {"hrrpua": 500, "xb": [..]}'), and by tying the boolean flags to concrete rules it checks (user confirmation, fires the user did not ask for).

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 precise verb and object — 'Review the sequence of tool calls you intend to make BEFORE calling them' — and enumerates the exact checks performed (tool/arg name validation against app or snapshot, BULC rules, HRR from HRRPUA × area, mesh ordering). It is clearly distinguishable from validate_project, sim_preflight and bulc_check_deck, which validate artifacts rather than a planned call sequence.

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 temporal guidance is explicit and front-loaded ('BEFORE calling them'), and the rule list implies the situations it covers (fires, sim runs, meshes, import ordering). It does not, however, state when NOT to use it versus siblings like bulc_check_deck or validate_project, so the agent must 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 establish read-only, idempotent, non-destructive, local (openWorldHint=false) behavior, so that burden is lifted. The description adds real value beyond them: the PNG is returned both as an image and a path, savePath writes a file to the local PC, and the capture requires a live app — none of which the annotations convey.

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 purpose, then parameter semantics, then return behavior — a good funnel. The duplicated '[bulc-mcp] Returns the picture as an image' sentence repeats the first paragraph, and the trailing rules-reference line is boilerplate rather than descriptive 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?

No output schema exists, so the description correctly steps in to describe the return (image plus path, optional file copy). For a 5-param, zero-required capture tool the definition is nearly complete; only edge cases like maxWidth's default interplay and failure modes when no app is running are unstated.

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 only 60% (view and region carry enum values but no descriptions), so the description must compensate — and it does, explaining each view enum value's meaning and that region=viewport captures only the drawing area vs. window. It says nothing extra about maxWidth beyond the schema, and savePath's absolute-path requirement is already in 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?

States a specific verb+resource: 'Screenshot of the running app for visual checking', then enumerates the five view modes (current/2d/3d/result/shape) so the agent knows exactly what each capture targets. This differentiates it from shape_screenshot (Shape Studio-specific) and result_* siblings.

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 clear context ('for visual checking') and a hard prerequisite ('Live app only'), plus the 'story = story id to show in 2D' routing rule. It does not, however, explicitly name an alternative for capturing Shape Studio (shape_screenshot) or state when this is the wrong choice.

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=false, idempotentHint=false and destructiveHint=false, so the write-and-non-repeatable profile is covered. The description adds a small amount of behavioral context by flagging that EVAC-001/GEO-002 rules govern this operation and pointing to bulc_knowledge_search, but it says nothing about side effects on existing stories or what the new story inherits.

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 lines, front-loaded with the core action, with no padding. The rule-reference line is terse and somewhat cryptic but does not waste 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?

For a zero-parameter mutation with no output schema and descriptive annotations, the definition is minimally adequate: it says what is created. It omits how the new story relates to existing stories (ordering/height defaults) and what the caller should expect back, which an agent would reasonably want before invoking a non-idempotent write.

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 tool takes zero parameters, so the schema carries no parameter semantics to explain and the baseline is 4. The description's clarification that a 'story' is a floor level is the only semantic annotation needed.

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: 'Add a new building story (floor level)'. The parenthetical clarifies the domain term 'story', and the verb 'add' cleanly distinguishes it from siblings draw_remove_story, draw_list_stories and draw_update_story. It stops short of naming any sibling explicitly, so it is clear but not fully differentiated.

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 statement of when to use this versus draw_update_story or draw_set_wall_params, nor any prerequisite (e.g. whether a project/story must already exist). The only contextual pointer is the cryptic '[bulc-mcp rules] EVAC-001, GEO-002 — bulc_knowledge_search "<id>"' line, which hints that rules apply but does not tell the agent when this tool is the right choice.

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, idempotentHint=true, and destructiveHint=false. The description merely repeats 'read-only' and adds no further behavioral context such as ordering, pagination, or what the story list 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 first sentence is concise and front-loaded. The second line, '[bulc-mcp rules] EVAC-001, GEO-002 — bulc_knowledge_search "<id>"', is cryptic and does not clearly earn 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 simple, parameterless, read-only list operation with rich annotations and no output schema, the description is nearly complete. The missing piece is any indication of when to prefer this tool over other project-inspection tools.

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 tool takes zero parameters, so per the rubric the baseline is 4. The empty schema needs no additional parameter explanation from the 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 a specific verb and resource: 'Get current building stories list'. This distinguishes it from write-oriented siblings like draw_add_story and draw_remove_story, though no sibling is named explicitly.

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 does not say when to use this tool versus alternatives such as get_object_properties or list_obstacles. The only contextual hint is '(read-only)', which describes safety rather than usage conditions.

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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds nothing beyond that — it does not say what happens to dependent geometry, walls, or doors when a story is removed, nor whether confirmation is required.

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 core sentence is short and front-loaded with the verb and resource. However, the appended '[bulc-mcp rules] EVAC-001, GEO-002 — bulc_knowledge_search' fragment is noise that does not belong in a tool description and hurts density.

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 one-parameter destructive delete with annotations covering the safety profile and a fully documented parameter, the essentials are present. It falls short of complete because no side effects or preconditions for removing a story are described and the stray rules line distracts.

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 the single required id parameter is documented as 'Story ID to remove'. The description adds no format, type, or sourcing detail beyond the schema, so this is 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?

States a specific verb and resource: removing a building story, identified by ID. It is clearly distinguishable from draw_add_story, draw_update_story, and draw_list_stories, though it does not explicitly name those siblings. The purpose is unambiguous.

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 when-to-use or when-not-to-use guidance, no prerequisites, and no mention of alternative story tools. The trailing bracketed line appears to be template/rule leakage rather than actionable usage instruction, so it does not compensate.

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=false (a mutation), idempotentHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds the meaningful qualifier "default," indicating these values apply to subsequently created doors rather than an existing one, but says nothing about scope of effect or whether prior doors are 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 purpose is front-loaded and the tool name phrasing is efficient, but the appended rule citation is unexplained clutter that a reader cannot decode without the bulc_knowledge_search tool. Half the description is opaque rule metadata rather than actionable 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?

With annotations covering mutation/idempotency and full schema coverage for both parameters, the description only needs to convey purpose - which it does. It is minimally adequate, though for a config setter it could say where the defaults take effect.

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%; both doorWidth and doorHeight already document units (m) and defaults (0.9, 2.1). The description adds no further parameter meaning, 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+resource ("Set default door dimensions") that clearly distinguishes it from siblings like draw_set_wall_params and draw_set_window_params. The word "default" correctly signals a global config setter rather than a per-door edit, but there is no explicit sibling differentiation in the text itself.

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 when-to-use guidance is given. The cryptic rule citation ("[bulc-mcp rules] EVAC-001, GEO-002 — bulc_knowledge_search") hints at a related tool but does not explain when this setter should be invoked versus alternatives such as add_door or update_obstacle.

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=false, idempotentHint=true, destructiveHint=false, and closed-world, so the safety and idempotency profile is covered. The description adds the crucial scope detail that these are defaults for future drawings, not retroactive edits, but omits any mention of required permissions or what happens to already-drawn walls.

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 core sentence is a tight, front-loaded statement of purpose. The appended rule-reference line is cryptic and arguably noise, but it is short and does not bury the main 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?

For a two-param, fully-specified schema with a clear annotation profile, the core description is adequate. What is missing is the scope clarification that these are defaults applied to future drawing operations, plus any explanation of the referenced rules.

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