compare

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable behavior beyond annotations: 'Synchronous deterministic compute; nothing is persisted' and that runs/seed are forwarded. It doesn't discuss auth/error cases, but annotations lower the burden and the added context is meaningful.

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 front-loaded with the core purpose and then provides behavioral, parameter, and sibling-routing details. There is some redundancy between the early 'Use recommend...' sentence and the final 'Which to use...' sentence, but each sentence still adds information (the final one explicitly mentions simulate as an alternative), so it remains efficient.

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?

There is no output schema, so the description compensates by naming the returned fields ('recommended_action, expected_value, probability_of_loss, and delta_vs_best') and the winner rule. It covers input constraints, reproducibility, and side effects. Small gaps remain around error behavior and exact response shape, but the tool is simple enough that the description is largely 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 the baseline is 3. The description adds meaning beyond the schema by stating that 'Each scenario's request uses the simulate payload shape' and that 'runs and seed are forwarded for reproducibility', which clarifies how parameters relate to the simulation and to sibling tools.

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 uses a specific verb and resource ('Run 2-10 named scenarios side by side') and clearly states the output ('winner plus each scenario's deltas versus the best one'). It also names sibling tools explicitly ('use recommend...', 'simulate for one scenario'), so an agent can distinguish compare from recommend and simulate.

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 gives explicit when-to-use guidance: '2-10 named scenarios evaluated side by side with the winner by expected value'. It also provides alternatives and exclusions: 'use recommend for a ranked pick with rationale, or simulate for one scenario'.

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