run_candidate

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

No annotations are provided, so the description carries the full burden. It explicitly discloses that edits are applied to a copy, that validation against the EPANET engine occurs, that a simulation runs, and crucially that the base model and stored results are NEVER modified. This full side-effect disclosure is exactly what an agent needs, given the absence of annotations.

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 two sentences with no waste. It front-loads the core action and process, then delivers the critical non-modification caveat in a separate sentence. Every word contributes to the agent's understanding, making it appropriately concise and well-structured.

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 tool with 3 parameters (one a nested array) and no output schema, the description thoughtfully points to the return shape ('same shape as run_simulation'), describes the validation and simulation steps, and guarantees no side effects. This covers the essential information an agent needs to invoke it correctly, including what to expect back, without requiring an output schema.

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%, meaning every parameter (networkId, edits, quality) already has detailed descriptions. The tool description adds no parameter-specific meaning beyond restating that edits are applied to a copy (which is already in the schema's edits description). With high schema coverage, the baseline is 3, and no additional semantic value is provided.

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 ('Evaluate') and resource ('a scenario'), and enumerates the exact actions: applying batch edits to a copy, validating, running a simulation, and returning results. It differentiates itself from run_simulation by explicitly noting it operates on a COPY and returns the same shape, and it lists the edit kinds, making it clearly distinct from set_* and run_simulation.

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?

The description implies when to use: for evaluating candidate edits without altering the base, and it contrasts with run_simulation by noting the same return shape. The phrase 'candidates can be compared freely and previous runs stay valid' gives clear context for scenario testing. It doesn't explicitly say 'use this instead of run_simulation when you want to test changes', but the intent is readily inferable.

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