compare_distributions

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

With no annotations, the description discloses the tool's behavior: it computes differences and dominance under a specific convention (larger outcomes preferred). It also notes the prerequisite of a prior simulation. However, it doesn't mention potential errors or state mutations (though likely read-only).

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 a single paragraph of three sentences, covering purpose, metrics, and usage context. It is efficient but includes a bit of explanatory text on stochastic dominance that, while helpful, adds length.

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?

Given the complexity of comparing distributions, the description explains key statistical concepts and prerequisites. An output schema exists, so return values are documented elsewhere. It could mention default max_n behavior, but overall is sufficiently complete.

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 each parameter already has a description in the input schema. The description adds context about per-iteration samples but does not provide significant new meaning beyond the parameter descriptions.

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 clearly states the tool compares two simulation outputs head-to-head, specifying the exact metrics (mean/stdev/percentile differences, P(A>B), stochastic dominance). It distinguishes itself from sibling tools like get_simulation_results by focusing on comparative analysis and strategy selection.

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 provides explicit context: 'Use it to decide between strategies' and 'Run a simulation that records both outputs first.' It explains the dominance concepts but does not explicitly exclude alternative tools or state when not to use it.

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