run_calculation

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 determinism (fixed seed, same seed → same result), zero LLM involvement, fail-closed behavior on invalid input, and the full set of returned metrics. It omits cost/latency expectations and what exactly the 'errors' payload looks like.

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 core purpose is front-loaded, which is good, but the single dense sentence crams computation semantics, failure handling, return fields, and emoji/label rendering rules together. The presentation rules are useful but read as operator instructions that compete with the tool's purpose for attention.

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, and the description compensates by enumerating the return metrics (mean/median/p10/p90, P(best), expected_regret, tornado, top_uncertainties, label_text) and the invalid-map error path. Only the undocumented 'n' parameter and any performance expectations remain gaps.

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% and the schema documents nothing, so the description must compensate. It only partially does: it establishes that 'map' must be a valid decision map and alludes to the seed being fixed, but 'n' is never mentioned and the seed's relationship to the parameter (is it settable, or forced?) is ambiguous rather than explained.

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 names a specific verb and resource: a deterministic Monte Carlo run over a valid decision map, and stresses that the computation is code-driven, not LLM-driven. That clearly separates it from siblings like validate_decision_map or save_decision_map, though it never names those siblings explicitly.

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?

It states the prerequisite (the map must be VALID), the failure path (invalid map → refusal with errors, fail-closed), and how the output should be presented (only alongside the 📐 frame, never mixed with other labels). It gives clear context but does not name an alternative tool or route the agent to validate_decision_map first.

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