Add surface

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.