Add sprinkler

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.