solve_for

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

The description goes well beyond the annotations (readOnlyHint=false, destructiveHint=false): it discloses the algorithm, the on-failure post-condition ('error reports it at both bounds and nothing changes'), and the on-success state mutation ('vary stays at the value found; the result is the operating point there'). This tells an agent exactly what state changes and what happens on partial failure, consistent with the 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?

Four sentences across three paragraphs with no filler: purpose first, then mechanism with example, then failure behavior, then success post-condition. Every sentence carries distinct information, and the 'as from solve' comparison earns its place by relating the output to a known sibling.

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 8-parameter numerical inversion tool with state mutation, the description covers the algorithm, parameter roles, the bounds-bracketing requirement, the failure mode, and post-conditions. Since an output schema exists, return-value details are appropriately delegated rather than repeated. The optional parameters (units, variables) are left to the schema, which already documents them well.

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 88%, so the baseline is 3, and the description adds relational meaning the schema cannot express: vary is the sole adjusted variable bounded by lower/upper, and the loop runs until target equals value. The worked example ties vary ('pump speed') and value ('15 m3/h') to concrete entities. It delegates per-parameter details to the already-rich schema, which is appropriate.

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 opening sentence defines the tool's precise role—finding the input or parameter value that yields a target result—and names the numerical method (Brent's method) with a concrete example (pump speed for 15 m3/h). The 'as from solve' reference situates it against its nearest sibling, framing solve_for as the inverse of solve, 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?

The goal-seeking context is stated clearly up front: adjust one input until a target equals a value. The failure clause also implies correct usage—bounds must bracket the target crossing, otherwise the error reports both bounds and nothing changes. However, it never explicitly names an alternative or a when-not-to-use condition; the 'as from solve' remark hints at the relationship but stops short of explicit routing.

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