Report Match Result

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

Annotations already declare the mutation profile (readOnlyHint false, idempotentHint true), but the description adds substantial context beyond them: one HTTP attempt, preservation of the original revision/result/winnerIds on explicit retry, consensus semantics (all accepted players must agree for confirmed), unconfirmed/disputed outcomes, and no automatic reward. The detailed error taxonomy (404/409 variants, 501, 401, 403, 429) with prescribed recovery behavior is unusually rich. It stops short of 5 only because the 'Not for' and 'Side effects' sections repeat the no-automatic-reward point.

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?

Front-loaded and clearly segmented with labeled sections (Use when / Not for / Requires / Side effects / Returns / Errors), so an agent can scan to the part it needs. It is long and contains some redundancy — 'automatic rewards' is excluded in the Not-for list and again as 'No automatic reward' under Side effects — which costs a point.

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 six-required-parameter mutation with no output schema, the description covers prerequisites (userId, sessionToken sourcing, HORIZON_API_KEY), side effects, the return shape {match,replayed,pollAfterSeconds,serverTime}, and every documented failure mode with recovery steps. An agent has everything needed to call it correctly and to recover from a 409 without corrupting state.

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 two things the schema does not: the cross-parameter relationship that sessionToken must be the accessToken from horizon_signin_email/horizon_signin_anonymous, and the immutability rule that finalStateRevision/result/winnerIds must never be substituted on an uncertain write. Those constraints materially change how an agent fills and re-fills the parameters.

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?

States a specific verb and resource — 'Records this participant's immutable report for the frozen final state' — which is unambiguous and distinct from siblings like horizon_submit_match_turn or horizon_advance_match_timeout. It also implicitly scopes itself to the final-state phase of a match, so an agent can tell it apart from turn submission without opening a 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?

Explicit 'Use when' (explicit asynchronous multiplayer actions after reading horizon://docs/matches) and 'Not for' (automatic polling, page traversal, timeout progression, invented winners, automatic rewards), plus a direct routing instruction to reconcile with horizon_get_matches and horizon_get_match. This is the full when/when-not/alternative triad.

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