Spr set defaults

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

Annotations establish write/idempotent/non-destructive, and the description adds genuinely useful scope semantics: defaults apply only to new objects and to 'heads without an explicit profile', so it will not retroactively overwrite existing configuration. It also clarifies cross-parameter behavior ('auto = zone deluge when zones exist', 'false = only open nozzles and drains discharge'). It stops short of stating auth requirements or exactly which existing values, if any, get overridden.

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 content volume is defensible for a 16-parameter tool, and the primary purpose is front-loaded. But it is delivered as a single sprawling sentence punctuated by semicolons and embedded parentheticals, which makes it hard to scan and separates related concepts (hydraulics vs. design basis) less clearly than short grouped sentences would.

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 16 optional parameters, no output schema, and annotations covering the safety profile, the description does cover every parameter group and the scoping behavior an agent needs to call it correctly. The remaining gap is that it never states the effect of supplying no arguments at all (all defaults are optional, so calling with an empty object is ambiguous).

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 an extra point by adding interpretation the schema lacks, notably that operation='auto' becomes zone deluge when zones exist, that includeClosedHeads=false means only open nozzles and drains discharge, and that drainCd/K-factor tie the drain hole to the sprinkler orifice. This clarifies interactions between parameters rather than just restating field 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?

The description opens with a specific verb ('Set') and enumerates exactly which defaults are being configured: pipe diameter/standard/K-factor, spray profile, minor-loss options, and the design basis (required pressures, operation mode, velocity limits). Critically it scopes these to 'new pipes/heads' and 'new projects', which distinguishes it from mutation tools like spr_set_pipes or spr_update_pipe that alter existing objects.

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 context is implied rather than stated: 'for new pipes/heads' and '(new projects on)' signal this is a pre-design configuration step, and the '[bulc-mcp rules] SPR-001...' pointer tells the agent to consult knowledge search. However there is no explicit when-to-use/when-not statement and no sibling tool is named as the alternative for updating existing pipes or heads.

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