simulate_matchup

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

The description explicitly discloses a state-mutating side effect: 'record=True logs the prediction for calibration'. Persisting a prediction record modifies the environment, which directly contradicts the declared readOnlyHint=true annotation. Because the description contradicts the annotations, this is an Annotation Contradiction.

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 purpose is front-loaded in the first clause and the outputs are listed immediately, so an agent can stop reading early. Sentences are dense and param notes are tucked in backticks rather than bulleted, and the dangling '(daily-gm does this)' plus the phantom `if_opponent_streams` add mild noise, but there is little outright waste.

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?

For a 5-parameter tool with no output schema and no parameter descriptions, the description compensates well by naming the returned statistics and explaining the streaming/record flags. But it leaves n and start undefined and, more importantly, contradicts the readOnly annotation regarding the record flag, so an agent cannot fully trust the behavioral picture.

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?

With 0% schema description coverage, the description must carry the parameter burden, and it does explain opponent ('team key or name'), opponent_streams ('adds optimally; 0 = skip'), and record ('logs the prediction for calibration'). However, n and start are left entirely unexplained, and the description references an `if_opponent_streams` parameter that does not exist in the schema, which risks confusing invocation.

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 states a specific operation (Monte Carlo matchup simulation) against a named resource (rest-of-week matchup vs an opponent) and enumerates concrete outputs (per-category win/tie/loss odds, expected categories won, swing categories). It is clearly distinguishable from siblings like scoreboard or playoff_outlook, which do not simulate matchups. It stops short of 5 only because it never explicitly names an alternative tool.

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?

There is no when-to-use / when-not-to-use guidance and no mention of alternatives among the roughly 50 siblings (e.g., scoreboard, playoff_outlook, optimize_lineup). The closest thing to context is the parenthetical '(daily-gm does this)', which hints at a caller but gives the agent no decision rule for choosing this tool.

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