Balance report

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

With no annotations, the description carries the full burden and does so well: it discloses that all numbers are averages ignoring variance, crits, misses, states, items and elements beyond skill/trait specs, and that it emits warnings for unevaluable formulas, downward curves, one-hit-kill or immune enemies. That is precisely the behavioral context needed to trust or discount the output.

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 numbered enumeration of the four report sections is front-loaded and easy to scan, and nearly every clause adds information. It is a dense run-on paragraph in places (especially the long final sentence about averages), which costs it a point on readability.

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, but the description effectively substitutes for one by describing the four result tables and the trailing warnings block. With five all-optional parameters and defaults stated, an agent has everything needed to call it correctly and interpret what comes back.

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, but the description adds meaning by mapping parameters to output sections and restating the key defaults (attackers default to the starting party, reference enemy defaults to median HP). It stops short of explaining how attackers' classId vs actorId interact, which the schema leaves largely implicit.

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 opens with a specific verb and resource ('Measure the game's balance from its data') and then enumerates the four concrete report sections it produces (class curves, damage-by-level, attacker/enemy matrix, enemy threat). An agent can distinguish it from sibling analysis tools like analyze_progression or simulate_battle without reading the schema.

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 explicitly names the alternative and the condition that selects it: 'use simulate_battle for a full fight', contrasted with this tool's averaged, no-variance/no-crit/no-miss approximation. Defaults for attackers, levels and reference enemy are also stated, so the agent knows when inputs can be omitted.

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