Hvac set defaults

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

Annotations already declare the write, idempotent, non-destructive profile, so the bar is lower. The description does add one genuinely useful behavioral fact — the values are defaults applied to *new* ducts, not retroactive edits to existing ones — but it omits persistence scope (project/session/level) and the trailing '[bulc-mcp rules] HVAC-001' fragment adds confusion rather than clarity.

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 tight and front-loaded. The second fragment referencing bulc-mcp rules and a bulc_knowledge_search id placeholder is unexplained noise that does not earn its place in a tool 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?

For an idempotent six-parameter setter with full schema documentation and no output schema, the description covers the core action adequately. It nevertheless omits where the defaults take effect and how they interact with ducts already created, which an agent would need to avoid misusing it.

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 all six parameters (width, height, diameter, material, ductShape, airflowCFM) individually documented in the schema, so the baseline is 3. The description restates only three of them (shape, diameter, material) and adds no syntax, units, or interaction details 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 and resource: 'Set default duct shape, diameter, and material for new ducts'. The 'for new ducts' qualifier scopes the operation, distinguishing it from duct-editing siblings like hvac_update_duct or hvac_add_duct. It stops short of naming a sibling or clarifying project-level vs. level-level scope, so it's 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?

Usage is only implied: the phrase 'for new ducts' tells the agent this configures defaults that apply going forward rather than altering existing ducts. There is no explicit when-to-use, no prerequisites, and no mention of nearby alternatives such as hvac_update_duct or spr_set_defaults.

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