sim_sweep

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

With no annotations, the description carries the full burden and does well: it discloses that the original value is restored afterwards even on error, that a diverging solver is recorded as a result rather than raised, and that everything runs in a single session. It omits permission/auth or performance/timeout caveats, but the key state and error-handling behaviors are disclosed.

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?

Purpose is front-loaded in the first sentence, followed by tightly packed behavioral and parameter detail. No filler sentences, though the enum lists make it read a touch list-like rather than prose.

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?

An output schema exists, so return values need no explanation. Given the 4-param schema at 0% coverage and no annotations, the description covers the essential behavior and parameter meaning adequately, though it never states the result shape for a sweep (per-value outcomes) which would help an agent interpret output.

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 0%, so the description must compensate, and it largely does: it enumerates the valid param choices (stiffness, damping, effort, or coupling:<follower>), the test options ("wave" or "range"), and explains steps. The values array is only implied as the set to sweep, leaving its semantics slightly thin.

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: comparing several values of one live parameter within a single session. The sweep scope functionally distinguishes it from sim_set_params (single set) and sim_wave/sim_range_test (single run). It does not explicitly name any sibling, so it stops short of a 5.

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 mechanics (apply each value, run the test, restore) imply the use case of parameter comparison, but there is no explicit when-to-use, when-not, or routing to alternatives like sim_set_params or sim_range_test. Usage is implied rather than stated.

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