set_demand_pattern

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

With no annotations present, the description carries the full burden — and it delivers extensively: EPANET validation rules (id validity, multiplier bounds 0–10, non-all-zero, junction existence/type), model re-parse guarantee with unchanged node/link counts, solvability preservation, precise replacement semantics (in-place overwrite, junctions re-assigned), and invalidation of prior simulation results. This is exemplary disclosure of behavior beyond the schema.

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 long (~150 words in a dense block) but every sentence earns its place given the tool's complexity — validation rules, replacement semantics, and post-conditions are all load-bearing, not filler. The essential purpose is front-loaded before the validation details, though a slight structural tightening would help.

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 four-parameter tool with no output schema and no annotations, the description is remarkably complete: it covers validation/failure modes, replacement behavior, effect on existing patterns and junctions, invalidation of results, and the correct follow-up steps. An agent has everything needed to invoke it correctly and understand consequences.

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, but the description adds genuine value on top: it explains that 24 multiplier values correspond to an hourly diurnal pattern, that the average multiplier scales the daily total, and suggests averaging 1.0 to keep daily demand unchanged. It also clarifies the junctionIds semantics (the [JUNCTIONS] demand column or [DEMANDS] entries) beyond the schema's summary.

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+target ('Add or replace a demand pattern and attach it to one or more junctions') and the reason (make base demands vary over simulation, with the diurnal-curve example). This distinguishes it cleanly from siblings like set_junction_demand (static per-junction demand) and assign_demands, so an agent can tell them apart 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?

Gives clear context of when to use ('so base demands vary over the simulation') and routes forward with explicit tool names: use get_nodes to list junction ids, re-run run_simulation afterwards, and get_node_results with timesteps to see hourly variation. It does not, however, name the static-demand alternative (set_junction_demand) as a when-not-to-use exclusion, falling just short of a 5.

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