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

Goes well beyond the annotations: it states exactly what is consumed (the incoming request plus any crossed request), what is created on both sides, that the confirmation is sent atomically, and that repeating the same revision cannot double-apply — which operationalizes idempotentHint=true with real semantics. The error catalogue (REVISION_CONFLICT, FRIEND_REQUEST_NOT_FOUND, INBOX_FULL, capacity limits, 401/403/429) with per-code remediation is rich behavioral context the annotations cannot convey.

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?

Well front-loaded and cleanly sectioned (Use when / Not for / Requires / Side effects / Returns / Errors), with no filler about the tool's purpose. It is long and slightly redundant — 401 handling is covered twice (expired session vs. wrong HORIZON_API_KEY) — but for a destructive, revision-guarded mutation nearly every clause carries operational weight.

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?

With five required parameters, no output schema, and destructive+idempotent semantics, the description supplies everything an agent needs: auth prerequisites, the exact snapshot/revision contract, the full returned snapshot shape and cache-replacement instruction, the lastActiveAt caveat, and a complete error-to-recovery mapping. Nothing material is left to inference.

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 baseline is 3, but the description earns extra: it explains how to obtain sessionToken (sign in via horizon_signin_email or horizon_signin_anonymous and pass the accessToken) and stresses that expectedRevision/requestId must come from the reviewed snapshot rather than a refreshed one. That is invocation guidance the schema does not provide, though it does not document targetUserId or the userId/403 token-ownership tie in detail.

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?

Opens with a specific verb + resource ("Accepts Friend Request") and immediately qualifies the mechanism ("using the reviewed player revision"), which separates it from horizon_decline_friend_request and horizon_cancel_friend_request in the sibling list. An agent can pick this tool without opening any 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" and "Not for" sections rule out automatic retries, automatic acceptance of crossed requests, and silent expectedRevision substitution — unusually clear exclusions for a social-write tool. It stops short of naming the sibling to use instead (e.g. decline/cancel), so it lands at 4 rather than 5.

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

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

Goes well past the annotations: discloses that the exact invitation is consumed, limits/blocks are rechecked, the issuer is notified, and that same-revision replay cannot produce a second effect — consistent with idempotentHint=true and destructiveHint=true rather than contradicting them. Adds concrete HTTP-status semantics (409 revision conflict, REQUEST_NOT_FOUND, INBOX_FULL rollback, 429 no retry) that annotations cannot express.

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 with purpose then clearly labeled sections (Use when / Not for / Requires / Side effects / Returns / Errors), making it scannable despite its length. Minor redundancy in the error tail, where 429 and the 401/HORIZON_API_KEY case are restated.

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?

No output schema exists, yet the description specifies the return shape ({groups: MyGroupsView, group: GroupView|null}), the privacy scope of groups, and the cache-invalidation instruction. Auth, side effects, idempotency, and failure reconciliation are all covered for a destructive 5-param mutation.

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 already 100%, but the description adds operational meaning: how to obtain sessionToken (sign in via horizon_signin_email/horizon_signin_anonymous and pass the accessToken), and that expectedRevision must be the reviewed revision and requestId the exact pending identity. Slight redundancy with the schema's own hints, hence not a 5.

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+resource: applies the accept-group-invite action against a reviewed group revision, and that it consumes the player's exact invitation. It does not explicitly distinguish itself from nearby siblings horizon_accept_group_request or horizon_decline_group_invite, so the agent must infer invite-vs-request semantics from the name alone.

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' and 'Not for' clauses name the triggering condition (player explicitly confirms the action) and three exclusions (replacing reviewed revision/requestId, bypassing a leader's block, automatic retry after uncertainty). It also routes reconciliation to horizon_get_groups and horizon_get_group_pending.

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

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

Beyond the annotations, it discloses atomic admission and confirmation, no automatic retry, same-revision replay safety, return shape, and a detailed error-handling model. These details materially help an agent understand a destructive, idempotent, open-world mutation.

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 structured and front-loaded with purpose, usage, requirements, side effects, returns, and errors. It is long, especially in the error section, but most content is useful for this complex mutation tool.

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?

Given six required parameters, no output schema, and destructive/idempotent annotations, the description is complete: it explains authentication, side effects, return shape, idempotency behavior, and recovery from conflicts and errors.

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 schema already documents all six parameters well. The description reinforces key constraints around sessionToken, expectedRevision, and requestId, but adds little semantic meaning beyond what the schema descriptions already provide.

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 clearly names the action as accepting a group request and ties it to the reviewed group revision. It is specific enough to distinguish from related tools like decline_group_request or accept_group_invite, though it does not explicitly contrast those siblings.

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 states when to use the tool ('the player explicitly confirms this group action') and when not to use it ('replacing reviewed revisions/request IDs, bypassing a leader's block, or retrying automatically after uncertainty'). It also directs reconciliation to horizon_get_groups and horizon_get_group_pending.

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

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

Goes well past the annotations: atomic delta application, archived templates and rule-less properties being unadjustable, a single HTTP attempt only, cache replacement scoped to the matching host/project/player, and a full error taxonomy (409/404/422/401/403/429) with required remediation for each. This is exactly the behavioral context a destructive mutation needs on top of destructiveHint/idempotentHint.

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?

Labeled sections (Use when / Not for / Requires / Side effects / Returns / Errors) make it scannable and the purpose is front-loaded. The error enumeration is long and slightly repetitive (401 and 429 are explained in two places), which is the only real 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 destructive, revision-guarded mutation with no output schema, it covers everything an agent needs: auth chain, atomicity, return shape ({userId,revision,instances,limits,serverTime}), cache handling, and failure semantics. Nothing material is missing.

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 earns more by explaining what the parameters mean operationally: expectedRevision is the exact reviewed revision that must not be silently substituted, sessionToken is the accessToken from sign-in, and changes are deltas subject to server rules and archived-template restrictions. It does not document the per-key format or the 8-item cap, but the schema already carries those.

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 ('Adjusts Item Properties') plus the scoping constraint that it operates against a reviewed inventory revision, which separates it from catalogue/equip/discard siblings by implication. It never names an adjacent sibling (e.g. horizon_equip_item, horizon_discard_item) explicitly, so the differentiation is inferred rather than stated.

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?

Gives an explicit 'Use when' trigger (player explicitly requests this inventory action), an explicit 'Not for' exclusion list (automatic retries, client grants, forcing IDs/revisions), and names the concrete alternative path on conflict: horizon_get_items plus reconciliation. It also names the prerequisite sign-in tools (horizon_signin_email / horizon_signin_anonymous) and how to feed their accessToken in.

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

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

Annotations already declare mutation, open-world, idempotent, and destructive behavior, and the description goes well beyond them by explaining operationId replay semantics, no automatic ID creation or retries, full side effects, auth requirements, return states, and specific error meanings. Nothing contradicts the annotations.

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 long but well front-loaded and explicitly structured with Use when / Not for / Requires / Side effects / Returns / Errors. The density is justified by the mutation, auth, idempotency, and error-handling complexity, though it is close to overloaded.

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?

Given the lack of an output schema and the tool's destructive/idempotent nature, the description supplies the missing operational context: return shape, replay states, error recovery instructions, auth prerequisites, and rate-limit behavior. An agent has enough information to invoke and recover correctly.

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 per-field descriptions already carry most parameter semantics. The tool description adds useful operational meaning beyond the schema, particularly around operationId idempotent replay, signed amount application, and reason/payload guard behavior.

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 ('Adjusts one player value') plus scope constraints (enabled project rules, per-call and daily limits). It explicitly distinguishes itself from horizon_get_player_values and horizon_purchase_player_value_offer, so an agent can route without inferring from sibling names.

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?

Gives explicit 'Use when', 'Not for', and alternative-tool guidance, including the purchase alternative and inspection sibling. It also states the prerequisite that adjustment must be enabled and the authentication flow needed before calling.

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

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

Beyond annotations, it discloses one HTTP attempt, auth/session requirements, revision-conflict handling, side effects, return fields, rate limits, and error semantics. This is exactly the kind of behavioral context an agent needs for a destructive open-world mutation.

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?

It is well organized with front-loaded Use/Not for/Requires/Side effects/Returns/Errors sections. But it is long and includes start, turn, leave, cancel, and Inbox side effects that do not obviously belong to advancing a match timeout, so not every sentence earns its place.

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 destructive open-world mutation with no output schema, it covers auth, return shape, conflicts, rate limits, and key failure modes. The agent has enough to call correctly, even if scope wording could be tighter.

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 useful semantics for sessionToken (pass accessToken as Bearer) and expectedRevision (original reviewed revision, never substitute), though matchId remains schema-only.

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 opening sentence names a specific operation and revision constraint: execute an advance match timeout under the original revision. However, it does not clearly differentiate this tool from siblings like horizon_start_match, horizon_submit_match_turn, or horizon_leave_match, and later sentences mention those sibling behaviors, muddying scope.

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 gives explicit 'Use when' and 'Not for' conditions and points to horizon_get_matches and horizon_get_match for reconciliation. The exclusion of automatic polling and the auth setup are concrete guidance for selecting and invoking the tool.

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

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

Goes well beyond the annotations: atomic removal of friendship and both request directions, no notification to the blocked party, no automatic retry, and idempotency keyed to the revision. It also documents auth requirements, cache replacement, and specific error semantics (409, 404, INBOX_FULL, 401, 403, 429), which is exactly the behavioral detail needed for a destructive mutation.

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 with the core action and organized into labeled sections (Use when, Not for, Requires, Side effects, Returns, Errors), so it is easy to scan. It is dense and long, but most sentences carry operational value for a destructive, idempotent mutation; a few error details could be trimmed without losing meaning.

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?

Even without an output schema, the description specifies the returned snapshot shape and instructs the caller to replace the matching cache. It also covers auth, side effects, idempotency, and error recovery, leaving nothing critical for an agent to infer before invoking the tool.

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 real meaning: sessionToken must be the accessToken from horizon_signin_email or horizon_signin_anonymous, and expectedRevision must come from a reviewed snapshot and never be silently replaced. The 409 guidance reinforces how expectedRevision is intended to be used.

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 ('Blocks Player') and adds scope ('using the reviewed player revision'), so the action is unambiguous. It does not explicitly contrast with the sibling horizon_unblock_player, but the name and description make the distinction clear enough without opening 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?

Explicitly names the triggering condition ('the player explicitly requests this social action') and enumerates exclusions: no automatic retries after timeout, no automatic acceptance of crossed requests, and no silent expectedRevision changes. This is a textbook when/when-not section with no inference required.

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

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

Annotations already declare the destructive/idempotent/open-world profile, but the description goes well beyond them: it discloses that settlement is atomic (buyer debit, seller credit, fee, item transfer), that competing buyers cannot both settle, that the original intent must be persisted before sending, and it gives a concrete returns shape plus per-status-code error semantics (409, 422, 429, 401, 403, OPERATION_NOT_FOUND, full Inbox). The 401/403 guidance and the 'never fresh revisions or operation IDs on unknown outcome' rule are exactly the kind of context annotations cannot carry.

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?

Well front-loaded (purpose → when/not-for → requires → side effects → returns → errors) and nearly every line is actionable for a destructive purchase. Minor redundancy remains: 401 and 429 are each explained twice (in the error list and again in the closing failure paragraph), and 'Needs HORIZON_API_KEY' sits awkwardly inside the behavior text.

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 an eight-required-parameter, destructive, no-output-schema tool, this covers the gaps that matter: auth acquisition, atomicity and concurrency guarantees, replay/retry discipline on unknown outcomes, return shape, and per-status error handling. An agent has everything needed to call it safely.

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 would be 3, but the description adds real meaning: it tells the agent to obtain sessionToken from horizon_signin_email/anonymous and pass it as userId-matched Bearer, and it explains that revision, price and currency must be the *original* values held across retries, which reinforces the schema's 'never replace' notes with a coherent story.

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 with precision: 'Purchases the exact listing under its original revision, currency and price.' It also draws a boundary against automatic trading and price polling, and names horizon_get_marketplace_operation as the reconciliation sibling, so an agent can distinguish it from the other marketplace tools without opening schemas.

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 marketplace actions after reading horizon://docs/marketplace) and 'Not for' (automatic trading, price polling, generated replacement operations), plus a named alternative for the reconciliation case. 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.

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantial value beyond them: irreversibility ('cannot be restored'), the same-API-key constraint, required HORIZON_API_KEY, error semantics (isError with HTTP status/body), and specific 401/429 meanings including rate limiting. This is rich behavioral context layered on top of the structured hints.

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?

Well front-loaded with a labeled Use when / Not for / Requires / Side effects / Returns / Errors structure that scans cleanly. Slightly verbose: horizon_get_email_status and HORIZON_API_KEY are each referenced twice, and the error paragraph is dense, costing some tightness.

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?

With no output schema, the description supplies the return value ({message: 'Email cancelled'}), error behavior, prerequisites, and side effects. An agent has everything needed to call it correctly and interpret results.

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% and documents emailId, so the baseline is 3. The description adds useful provenance — the emailId comes from horizon_send_email and must be sent with the same API key — which meaningfully constrains correct invocation beyond the schema text.

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 precise verb and resource ('cancels a queued email') plus the crucial scope qualifier ('still pending... so it is never delivered'). This clearly distinguishes it from horizon_send_email and horizon_get_email_status among the large sibling set.

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' (scheduled email no longer wanted), 'Not for' (already processing/sent, cannot be recalled), and a named alternative ('check with horizon_get_email_status first when unsure'). The when/when-not routing is fully spelled out.

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

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

Annotations already declare destructive=true and idempotent=true, but the description adds the concrete mechanics: exactly which records are removed, that repetition cannot double-effect, that the returned snapshot should replace the cache, and the lastActiveAt semantics. It also documents auth requirements, error taxonomy (409, 404, INBOX_FULL, 401, 403, 429), and rate limiting — far beyond what the annotations supply.

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 with the action, then organized into labeled sections (Use when / Not for / Requires / Side effects / Returns / Errors). It is long but largely earns the length for a destructive, revision-guarded mutation; some error prose (e.g. HORIZON_API_KEY, 429 rate-limit explanation) could be tightened.

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?

No output schema exists, but the description fully specifies the returned snapshot shape, cache-replacement guidance, and the failure surface. For a five-parameter destructive social action, an agent has everything needed to call it correctly and recover from conflicts.

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 relational meaning: sessionToken comes from horizon_signin_email/anonymous, expectedRevision must come from a reviewed snapshot and not be auto-substituted, and requestId must be the exact reviewed ID. It does not explain format details, but it meaningfully clarifies how to source these values.

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 ('Cancels Friend Request') and the exact object acted on ('this exact outgoing request'), which distinguishes it from horizon_decline_friend_request (incoming) and horizon_remove_friend (established friendship). The side-effects sentence makes the scope unambiguous.

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?

Gives explicit 'Use when' and 'Not for' clauses, including concrete exclusions such as automatic retries after timeout and silently swapping expectedRevision. The alternative behaviors (snapshot + reconcile) are named, so the agent knows what to do instead of calling this tool blindly.

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

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

Adds substantial context beyond the annotations: it names the required sign-in flow (horizon_signin_email / horizon_signin_anonymous → sessionToken), the exact side effect (leader/officer cancels this invitation), the no-auto-retry policy, the idempotency mechanism (same-revision replay cannot create a second effect), and cache invalidation scope. Error semantics (409 REVISION_CONFLICT, REQUEST_NOT_FOUND, INBOX_FULL rollback, 403 role/block, 429 rate limit, 401/403 session cases) are all disclosed.

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-loads the action, then when/when-not, requirements, side effects, returns, and errors in a sensible order. However it bloats: the final sentence re-explains the 401 and 429 meanings already given in the preceding error block, and the returns/cache sentence is compressed past 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?

For a destructive, open-world, six-required-parameter mutation with no output schema, the description covers auth sourcing, side effects, return shape, cache replacement scope, and the full failure/reconciliation protocol. Nothing material needed to invoke it correctly is missing.

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 already 100%, so the baseline is 3; the description earns above that by explaining the semantics of expectedRevision and requestId in relation to error codes (revision conflicts, REQUEST_NOT_FOUND meaning the request was removed/replaced) rather than just restating field types.

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 ('cancel group invite action using the reviewed group revision') and clarifies the actor ('Leader/officer cancels this exact invitation'). It does not, however, disambiguate from the closest siblings — horizon_decline_group_invite and horizon_cancel_group_request — so an agent must infer which cancel path applies.

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: the player explicitly confirms this group action' plus a 'Not for' clause excluding revision replacement, block bypass, and automatic retry. It also routes to horizon_get_groups and horizon_get_group_pending for reconciliation, but never explains why to pick this over decline/cancel_request siblings.

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

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

Annotations already flag destructive/idempotent, but the description goes well beyond them: it specifies that same-revision replay cannot create a second effect, that there is no automatic retry, that INBOX_FULL rolls back the entire action, and how 409/REQUEST_NOT_FOUND/403/429/401 each behave. Session sourcing (signin tools, accessToken as sessionToken) and the HORIZON_API_KEY dependency are also disclosed.

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?

It is well front-loaded and sectioned (Use when / Not for / Requires / Side effects / Returns / Errors), but the Errors block is bloated, restating 401 and 403 twice with overlapping explanations of token ownership and API-key failure. Several lines could be merged without losing guidance.

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?

With no output schema, the description supplies the return shape ({groups:MyGroupsView, group:GroupView|null}) and its cache implications, so an agent knows what state changes after the call. Combined with the error/reconciliation guidance, nothing needed to invoke this destructive mutation correctly is missing.

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 nevertheless adds real meaning by explaining where sessionToken comes from and warning that expectedRevision and requestId must come from the reviewed snapshot and never be refreshed after an uncertain response. It does not elaborate on userId/groupId beyond the schema.

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 side-effects line ('Cancels your exact join request') makes the resource and the actor precise: the player withdrawing their own pending join request, not a leader declining someone else's. The opening sentence ('Applies the explicit cancel group request action') is close to a restatement of the name, and no sibling such as horizon_decline_group_request or horizon_cancel_group_invite is named to sharpen the boundary.

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 uses explicit 'Use when' / 'Not for' framing, and the exclusions (don't replace reviewed revisions or requestIds, don't bypass a leader's block, don't auto-retry) are concrete and actionable. The positive trigger ('the player explicitly confirms this group action') is generic, though, and does not tell the agent when to pick this over declining or cancelling an invite.

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

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

Annotations already declare destructive/open-world/idempotent, but the description adds real value: exactly one HTTP attempt with the persisted UUID/time/revision, cancel and receipt replay remaining available while trading is disabled, claim-through-Inbox rather than minting a replacement, and itemized 409/422/429/401/403 error semantics with atomicity guarantees. Minor deduction because the 401 guidance is ambiguous — it is attributed both to a missing/expired session and to a wrong HORIZON_API_KEY, which could send an agent down the wrong recovery path.

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?

Labeled sections (Use when / Not for / Requires / Side effects / Returns / Errors) with the core action front-loaded make a long description scannable. It is somewhat over-stuffed — the error block runs many sentences and repeats the 401 case twice with different causes — so a portion of the text does not fully earn its place.

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 destructive six-required-parameter mutation with no output schema, the description covers authentication path, side effects, return shape, and failure modes. Everything an agent needs to call it safely and interpret failures is present.

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 earns an extra point by explaining where sessionToken comes from (sign in via horizon_signin_email or horizon_signin_anonymous and pass the accessToken) and by framing operationId/issuedAt/listingId/expectedListingRevision as the persisted original values that must never be regenerated on retry.

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 — cancels the original listing revision into a protected pending item return — which is far more precise than the title alone. It distinguishes itself from adjacent siblings by naming horizon_get_marketplace_operation and by excluding automatic trading, polling, and generated replacement operations.

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 marketplace actions after reading horizon://docs/marketplace) and 'Not for' (automatic trading, price polling, generated replacements), plus a named alternative for reconciliation. An agent can route correctly without reading any other definition.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, openWorldHint=true, and readOnlyHint=false. The description adds meaningful behavioral context: sign-in requirements, creator-only lobby cancellation, one HTTP attempt, point-read access loss for departing actors, and detailed error semantics. However, it also includes side-effect rules for unrelated operations (start, turn, timeout, active leave), which muddies the transparency for this specific tool.

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 a clear purpose sentence and uses labeled sections, but it is bloated with rules that apply to other tools, such as 'Start requires the creator and every joined UUID exactly once' and 'Turn requires the current unexpired actor.' Those sentences do not earn their place in a description for canceling a match lobby.

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 destructive mutation with no output schema, the description covers authentication, side effects, return shape, and error handling in detail. It is nearly complete for an agent to invoke correctly, with the main weakness being the extra unrelated match-operation rules rather than missing information.

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 100%, so the schema already documents all four parameters. The description nonetheless adds valuable semantics: it explains how sessionToken is obtained from horizon_signin_email or horizon_signin_anonymous, and it stresses that expectedRevision must be the exact original revision and never substituted after an uncertain write.

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 verb and resource: 'Executes cancel match lobby under the exact original revision.' It also distinguishes this action from siblings by noting 'Lobby cancel is creator-only' versus 'Active leave forfeits,' so an agent can tell it apart from horizon_leave_match without opening either 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 provides an explicit 'Use when' section and a 'Not for' list, which is more than most definitions offer. It also names horizon_get_matches and horizon_get_match for reconciliation, though it stops short of directly saying when to choose this over horizon_leave_match.

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

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

Annotations declare readOnlyHint=false and idempotentHint=true; the description supplies the reason — a valid check refreshes the one-hour idle timeout and nothing else changes — which is exactly the non-obvious behavior the hint implies. It further discloses that an invalid token is NOT an HTTP error (isAuthenticated=false), the API-key requirement, the 429 rate-limit meaning, and the isError contract on failures.

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?

Dense but well-labeled (Use when / Not for / Requires / Side effects / Returns / Errors) with the core purpose front-loaded. Slightly over-long: the recover-by-signing-in guidance appears twice (under Returns and implicitly under Not for), and the Returns detail overlaps the output schema.

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 two-parameter authenticated check, the description covers trigger, alternatives, prerequisites, side effects, success shape, and the full error taxonomy — more than enough even though an output schema already exists. Nothing an agent needs to call it correctly is missing.

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 schema already documents both parameters, but the description adds real meaning by naming the origin of each value (userId from signup/signin, token from horizon_signin_*) and explaining that a 400 means malformed input. Minor friction: the prose calls the token 'accessToken' while the schema property is 'sessionToken', resolving the synonym is left to the schema's own description.

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 (checks) and resource (a player's session token validity for a userId) up front, and explicitly differentiates itself from siblings like horizon_test_connection and horizon_signin_*. An agent can identify the tool's role without opening 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?

Provides an explicit 'Use when' trigger (before session tools when a token may have expired, or on game resume) and an explicit 'Not for' with named alternatives for both excluded cases. Nothing about tool selection is left to inference.

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

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

Although annotations already declare destructive, idempotent, and open-world behavior, the description adds substantial context: atomic claim marking, one-time grant or exact item restoration, no automatic retries or new action IDs, overdue rewards remaining claimable, required inventory refresh, and detailed error handling. These details do not contradict the annotations.

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 long but well structured with labels for use cases, exclusions, requirements, side effects, returns, and errors. Given the high-stakes claim operation and broad error surface, every section adds useful information rather than filler.

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 supplies the return shape and meaning of key fields, including replayed and playerValues. It also covers auth prerequisites, side effects, post-claim inventory refresh, and failure modes, making it complete enough for correct invocation.

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 schema already documents the three parameters, but the description adds meaningful auth semantics: sessionToken must be the accessToken from sign-in, userId must match the session token, and entryId should come from the inbox snapshot. It does not add much beyond the schema for entryId format, but the session/user relationship is useful.

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: "Claims an inbox reward once for the authenticated player." It also distinguishes this from related inbox operations by naming horizon_get_inbox as the source of the entry and explicitly excluding recipient changes or invented attachment amounts.

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 gives explicit "Use when" and "Not for" guidance, states the prerequisite auth flow via horizon_signin_email or horizon_signin_anonymous, and ties the call to an explicit player action on an entry returned by horizon_get_inbox. Alternatives and exclusions are clear.

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

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

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false): it discloses that each call adds a report and repeats create duplicates, that the session is marked crashed, that same-fingerprint reports form a group, and that resolved groups become REGRESSED on a newer version. It also documents auth (HORIZON_API_KEY), error behavior (400/401/429) and the isError contract.

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 with the core action, then cleanly segmented into Use when / Not for / Requires / Side effects / Returns / Errors. Despite its length, every section carries distinct information, so nothing is wasted.

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 14-parameter, 9-required mutation with a nested breadcrumbs array and no output schema, the description supplies return shape ({id, groupId, createdAt}), grouping semantics, auth requirements, and error handling. An agent has everything needed to invoke it correctly.

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 100%, so the schema already documents all 14 parameters including fingerprint grouping and sessionId provenance. The description adds only marginal meaning (userId optional, sessionId must come from horizon_create_crash_session), so the baseline 3 applies.

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 (Submits) and resource (a CRASH/NON_FATAL/ANR report with device data) plus the grouping model by fingerprint. It explicitly distinguishes itself from horizon_create_log and horizon_submit_feedback, so an agent can route correctly without opening schemas.

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?

Provides explicit 'Use when', 'Not for', and 'Requires' sections. It names the two alternatives (horizon_create_log, horizon_submit_feedback) with the conditions that select them, and specifies the sessionId prerequisite from horizon_create_crash_session.

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

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

Beyond the annotations, it discloses the side effect (one session recorded per call; a later crash report with the same sessionId marks it crashed), the return value, and a full error taxonomy: 400 validation, HORIZON_API_KEY requirement, 401 vs horizon_test_connection, and 429 per-minute rate limiting with retry guidance.

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?

Labeled sections (Use when / Not for / Side effects / Returns / Errors) make it skimmable, and the core purpose leads. Every sentence carries operational information; nothing is padding.

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?

With no output schema, the description supplies the return shape, the safety-relevant side effect, cross-tool ID reuse, and the error contract, which is more than enough for a 4-parameter ingest call.

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 100%, so the baseline is 3, but the description adds lifecycle meaning the schema lacks: sessionId must be new and unique per run and must be kept for horizon_create_crash_report. It does not add much about userId, platform, or appVersion beyond the schema.

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 ('Registers one app run (session)') plus the downstream purpose ('so horizOn can calculate the crash-free session rate'). It distinguishes itself from horizon_create_crash_report and the horizon_signin_* family without the reader needing to open 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' (once at every app start, with a new unique sessionId) and 'Not for' clauses that name the correct alternatives (horizon_create_crash_report for the crash itself, horizon_signin_* for player sessions). It even states the caller must retain the sessionId for the later report call.

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

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

Goes well beyond the annotations: requires prior sign-in via horizon_signin_email/anonymous and passing accessToken as sessionToken, explains that the retained player revision prevents duplicate creation on replay (consistent with idempotentHint), specifies that INBOX_FULL rolls back the entire action, that 403 covers bilateral block violations, and that 429 must not be auto-retried. This is exactly the extra context annotations cannot express.

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?

Well front-loaded with labelled Use when / Not for / Requires / Side effects / Returns / Errors sections. It is on the long side and repeats the 'never refresh the revision and repeat automatically' instruction twice (in the Not-for line and the Errors block), which is redundant rather than harmful.

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?

No output schema exists, and the description compensates by documenting the return shape ({groups, group}), the null-group case after leave/delete, the privacy boundary on private state, and which cache entries to replace. For a mutating, 7-param, nested-object tool, nothing an agent needs to call it safely is missing.

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 baseline is 3. The description adds a small amount of genuine value: it names where expectedPlayerRevision comes from (the current MyGroupsView revision) and clarifies that userId must match the signed-in Bearer session. It does not elaborate on joinMode or data, which the schema handles.

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 ('Creates a fresh server-identified group and its leader atomically') and the atomicity constraint distinguishes it from horizon_update_group and horizon_join_group. An agent knows exactly what this call produces without opening 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?

Explicit 'Use when' (player confirms group settings) and 'Not for' (choosing/reusing a group ID, resending uncertain writes with a new revision) sections, plus named alternatives (horizon_get_groups, horizon_get_group_pending) for reconciliation. This routing guidance is unusually complete.

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

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

Annotations already declare this as a non-idempotent, non-destructive write, and the description adds substantial context beyond that: one entry created per call with duplicates on repeat, the exact return shape ({id, createdAt}), tier-gated 403 behavior, 400 for bad userId, 401 API-key mismatch, and 429 per-minute rate limiting with a retry recommendation. It is fully consistent with the annotations.

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-loads the core action and uses clear labeled sections (Use when, Not for, Requires, Side effects, Returns, Errors) that make scanning easy. Some content is redundant, such as restating the BASIC-tier requirement in the 403 error note, which slightly dilutes an otherwise tight structure.

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 four-parameter write tool with no output schema, the description covers purpose, routing to siblings, auth requirements, side effects, return shape, and the expected error modes. An agent has everything needed to invoke it correctly and interpret failures without opening other resources.

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 100%, so all four parameters already have in-schema documentation (type enum, userId UUID source, message max length, errorCode grouping). The description restates the userId source and INFO/WARN/ERROR levels but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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 ('Writes one server-side log entry ... for a player') and pins the scope to the horizOn dashboard. It explicitly distinguishes itself from the two nearest siblings by naming horizon_create_crash_report and horizon_submit_feedback as different use cases.

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?

Has explicit 'Use when' and 'Not for' clauses, and the exclusion names the correct alternative tool for each case (crash report with stack trace, player-written feedback). Prerequisites (userId source, BASIC tier, no session token) are also stated, leaving nothing to inference.

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

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

Goes well beyond the annotations: one HTTP attempt, atomic removal of the exact inventory instance into escrow, persisted replay fields, and what 'replayed' means in the return. Error semantics are unusually rich — 409 reconciliation, 422 atomicity preservation, 429 no scheduled retry, 401/403 session distinctions, and the HORIZON_API_KEY / horizon_test_connection cross-check.

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?

Long but cleanly front-loaded with labeled sections (Use when / Not for / Requires / Side effects / Returns / Errors), which makes it scannable for a 9-parameter mutation. There is some redundancy and a mild internal tension: '429 schedules no retry' versus the later '429 ... wait a minute, then retry.'

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 destructive, open-world, 9-required-parameter mutation with no output schema, the description covers auth, atomicity, replay, return shape, and every documented failure mode. Nothing an agent needs in order to call this safely is missing.

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 real meaning: the original-field persistence contract (operationId, issuedAt, revisions must never be refreshed on retry) and which credential source supplies sessionToken. It does not explain the price/currency or duration semantics beyond the schema, so it stops short of a 5.

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 with scope: 'Lists one original unequipped item at the explicitly approved price and fee configuration.' It also names what it is not for (automatic trading, polling, generated replacement ops), which separates it from siblings like horizon_buy_marketplace_listing and horizon_cancel_marketplace_listing without needing their schemas.

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 marketplace actions after reading the docs) and 'Not for' exclusions, plus a named reconciliation alternative (horizon_get_marketplace_operation). The auth prerequisite is spelled out with concrete sibling calls (horizon_signin_email / horizon_signin_anonymous) to obtain sessionToken.

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

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

Beyond annotations, the description discloses atomic capacity and invite-slot reservation, lost-response reconciliation, revision/state conflict handling, 404 privacy behavior, 401/403 auth distinctions, 429 rate limits, and error-result behavior. These are material operational traits for a create operation.

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 purpose and organized into Use when, Not for, Requires, Side effects, Returns, and Errors sections. It is thorough for a high-stakes mutation, but the error block is long and somewhat repetitive, keeping it from being maximally concise.

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?

Even without an output schema, the description states the return shape and covers prerequisites, side effects, conflict semantics, and error cases. Combined with the annotations and fully described schema, an agent has enough information to invoke and recover from this tool correctly.

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 already 100%, so the baseline is 3, but the description adds useful meaning: sign in via horizon_signin_email or horizon_signin_anonymous and pass that accessToken as sessionToken. It also reinforces expectedRevision as the original reviewed revision, though it does not expand nested settings fields.

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 verb and resource: 'Creates one server-ID lobby under the original player-ledger revision.' It also scopes the action against reconciliation tools and lists exclusions, so the agent can distinguish this from get/list/start/join siblings without opening 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 gives explicit 'Use when' and 'Not for' guidance, including exclusions for polling, page traversal, timeout progression, and invented results. It also names horizon_get_matches and horizon_get_match for reconciliation, though it does not explicitly route creation versus start_match or join_match.

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

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

Discloses rich behavior beyond the annotations: atomic commit of object, usage, and quota; one HTTP attempt; retaining the original If-Match; return payload; and detailed 401/403/404/409/422/429 semantics. Annotations already indicate readOnly=false, openWorld=true, idempotentHint=true, and destructive=false, and the description adds operational context without clearly contradicting them.

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 and well-structured with Use when, Not for, Requires, Side effects, Returns, and Errors sections. It is dense and long, with some diagnostic detail that could be trimmed, but most sentences carry useful operational information.

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 complex mutation with no output schema, the description supplies the return shape, auth prerequisites, side effects, and a broad set of failure-mode instructions. It gives an agent enough context to invoke the tool correctly and handle common error states without needing to infer behavior.

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 100% schema description coverage, the baseline is 3; the description adds useful meaning around userId/sessionToken authentication flow, the 403 userId mapping, and treating expectedRevision as the original reviewed revision. It does not add much for collection, search, groupId, or position because those are already well-described in the schema.

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: creates one server-ID shared object using the original owner-usage revision. The 'Use when' and 'Not for' lines make clear it is not a polling, traversal, byte-interpretation, or combat-validation 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?

Provides explicit when-to-use and when-not-to-use guidance, including reading horizon://docs/shared-objects and avoiding background polling. It also names sign-in tools for authentication, but does not explicitly mention sibling alternatives such as horizon_update_shared_object or horizon_query_shared_objects for related operations.

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

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

Adds substantial context beyond annotations: exactly what gets removed (this incoming request plus the sender's outgoing record), that repeating a revision cannot double-apply, that no automatic retry occurs, and that the full host/project/player cache should be replaced from the returned snapshot. It also documents rate limits (429), auth failure modes (401/403) and the HORIZON_API_KEY dependency with per-status remediation.

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?

Labeled sections (Use when, Not for, Requires, Side effects, Returns, Errors) make it easy to scan and front-load the decision-relevant information. Slightly redundant: the no-automatic-retry rule is stated twice, once under "Not for" and again under "Side effects," and the error block is dense.

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 destructive, revision-guarded mutation with five required parameters and no output schema, the description covers prerequisites, concurrency semantics, side effects, the returned snapshot shape and cache-replacement guidance, plus every meaningful error path. Nothing an agent needs to call it correctly is missing.

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 baseline is 3, but the description earns extra credit by explaining provenance and constraints: sessionToken comes from horizon_signin_email/horizon_signin_anonymous accessToken, expectedRevision must be the current snapshot revision, and requestId must be the exact ID from the reviewed snapshot. It also clarifies that a 403 means the wrong userId was paired with the token.

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 ("Declines Friend Request") and immediately scopes it to the exact incoming request via the reviewed revision. The side-effects sentence ("Removes only this exact incoming request and the matching sender outgoing record") implicitly separates it from horizon_cancel_friend_request and horizon_remove_friend without the agent needing 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?

Explicit "Use when" and "Not for" sections give clear inclusion and exclusion criteria, including the important anti-pattern of auto-retrying after a timeout. It stops short of naming the concrete sibling alternatives (horizon_cancel_friend_request for outgoing, horizon_accept_friend_request for acceptance), so routing is inferred rather than stated.

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

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

Annotations already declare destructive, idempotent, open-world, and non-read-only behavior, and the description adds substantial context: removes the exact pending invitation on both sides, disallows automatic retry, and explains why same-revision replay cannot duplicate the effect. It also documents return shape, cache replacement scope, and error semantics including rollback and status-specific handling.

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 long but front-loaded and clearly sectioned into purpose, usage, requirements, side effects, returns, and errors. The detail is largely justified for a destructive, revision-sensitive operation, though it could be tightened in places.

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?

No output schema exists, but the description explicitly documents the return shape and meaning. For a complex authenticated mutation with revision and requestId constraints, it supplies enough behavioral, error, and reconciliation context for correct invocation.

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 useful meaning beyond the schema by tying userId and sessionToken to the sign-in flow, emphasizing that expectedRevision is the exact reviewed revision, and clarifying that requestId is the exact pending identity from the reviewed snapshot.

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: decline a group invite using the reviewed group revision. It is readily distinguishable from sibling actions such as accept, cancel, decline request, or leave group by the named action and required pending request identity.

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?

Gives explicit use conditions ('player explicitly confirms this group action') and explicit exclusions ('Not for replacing reviewed revisions/request IDs, bypassing a leader's block, or retrying automatically'). It also names reconciliation tools and specifies when to reconcile rather than retry.

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

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

Goes well beyond the annotations: declares the leader/officer authority requirement, the no-automatic-retry rule, idempotent same-revision replay, the exact return shape ({groups, group|null}) and its privacy scoping, and specific error semantics (409 REVISION_CONFLICT, REQUEST_NOT_FOUND, INBOX_FULL rollback, 403 role/session/bilateral-block, 429, 401).

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 with Use when / Not for / Requires / Side effects / Returns / Errors, so an agent can scan it quickly. It is dense and repeats itself in the error section (401 and 403 are each described twice, and HORIZON_API_KEY handling is restated at the end), which costs it 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 destructive, stateful group mutation with six required parameters and no output schema, it supplies auth prerequisites, authority requirements, the return contract, privacy guarantees, cache-invalidation guidance, and a full error/recovery map. Nothing an agent needs in order to call it safely is missing.

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 baseline is 3, but the description adds real meaning: sessionToken must be the accessToken from horizon_signin_email/horizon_signin_anonymous, expectedRevision is the reviewed revision that must not be refreshed-and-retried, and requestId is the exact pending identity from a reviewed snapshot. It does not explain targetUserId or groupId beyond the schema.

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 ('decline group request ... using the reviewed group revision') and clarifies the actor: 'Leader/officer declines this exact request'. That distinguishes it from sibling operations like horizon_accept_group_request, horizon_cancel_group_request, and horizon_decline_group_invite without needing the schemas.

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: the player explicitly confirms this group action' and 'Not for: replacing reviewed revisions/request IDs, bypassing a leader's block, or retrying automatically after uncertainty'. It also routes error recovery to horizon_get_groups and horizon_get_group_pending, naming the reconcile tools directly.

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

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

Beyond the annotations, the description discloses auth requirements, one HTTP attempt, revision-conflict behavior, 404/409/401/403/429 handling, and rate-limit semantics. Some listed side effects belong to other match operations, but the tool’s failure and concurrency behavior is unusually well documented.

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?

It is structured with Use/Side effects/Returns/Errors headings, but it is far too long for one operation. Large portions describe start, turn, timeout, active leave, lobby cancel, inbox, and ranked-run behavior that is irrelevant to declining a match invitation.

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?

The return shape and error/auth behavior are described, which matters because there is no output schema. However, the definition does not clearly explain the core effect of declining an invitation or the resulting match state, and it substitutes broad match-lifecycle material for focused semantics.

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 already 100%, so the baseline is 3, but the description adds meaningful auth context for sessionToken and userId by explaining the sign-in flow and passing accessToken as sessionToken. It also reinforces the expectedRevision rule, though matchId itself is not elaborated.

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 first sentence states a specific verb and resource, 'decline match invitation,' and adds the key constraint 'under the exact original revision.' It is clear enough to identify the action, but it does not distinguish this tool from adjacent invitation-decline or match-lifecycle siblings.

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 gives some usage guidance via 'Use when' and 'Not for,' but those apply broadly to asynchronous multiplayer actions rather than specifically to declining a match invitation. It names horizon_get_matches and horizon_get_match for reconciliation, yet does not explicitly say when to decline versus accept, leave, or cancel.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, yet the description adds real value: sole-leader precondition, the no-invitations/requests-remaining gate, no automatic retry, and same-revision replay producing no second effect. Auth path (sign in, pass accessToken as sessionToken), rate-limit behavior, and full error taxonomy are all disclosed.

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?

Labeled sections (Use when / Not for / Requires / Side effects / Returns / Errors) front-load the action and make it scannable, which is the right structure for a destructive tool. It is on the verbose side, with 401/403 handling restated in both the Errors and the trailing paragraph, costing some density.

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 specifying the return shape ({groups: MyGroupsView, group: GroupView|null}) plus the rule that groups is the actor's snapshot and never the target's private state. Error reconciliation steps, cache-replacement scope, and API-key failure modes are all covered, leaving nothing an agent needs to call this safely.

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 baseline is 3, but the description adds operational meaning: sessionToken must come from horizon_signin_email/horizon_signin_anonymous, and expectedRevision must never be refreshed and blindly retried after an uncertain response. That is semantic guidance beyond the field text, though it doesn't explain groupId versus any other identifier beyond what the schema says.

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 ("delete group action") and pins the mechanism to a reviewed group revision, which an agent can act on unambiguously. It stops short of naming the closest sibling (horizon_leave_group) that a player-vs-leader distinction should route away from, so the differentiation is implied by the side-effects clause rather than stated.

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: the player explicitly confirms this group action" and a "Not for:" list covering revision replacement, block bypass, and automatic retry. The exclusions target retry/state misuse rather than naming the sibling alternative (horizon_leave_group, horizon_transfer_group_leadership), so it falls short of full alternative routing.

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

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

Beyond the destructive/idempotent annotations, the description adds substantial context: owner cleanup surviving group leave/archive, the ABA-prevention rationale for retaining usage revision, the single-HTTP-attempt guarantee, the return shape, and detailed per-status error semantics (409/404/422/401/403) plus rate-limit and API-key failure guidance. This is precisely the value-add the dimension asks for.

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 purpose, then use/not-for, then side effects and errors; each block serves a distinct purpose. It is dense and the error paragraph is long, but nearly every sentence carries actionable information, so it avoids being padded.

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 destructive, revision-exact mutation with no output schema, the definition covers when to use it, auth prerequisites, side effects, return shape, and full error/reconciliation behavior. An agent has everything needed to call it correctly and recover from failures without guessing.

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 already 100%, so the baseline is 3, but the description adds real meaning: sessionToken must come from horizon_signin_email/anonymous accessToken, userId must be the player that signed in, and expectedRevision must never be swapped for a newer revision after an uncertain write. These are operational semantics not present in the schema text.

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 verb and resource ('Deletes one exact-revision object and refunds its stored charge') with a clear scope constraint (exact-revision, charge refund). It is distinguishable from update/get/create siblings by the revision-exact delete semantics, though it never names an alternative sibling tool explicitly, keeping it below a 5.

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 supplies an explicit 'Use when' condition (explicit world-map/async-PvP object access after reading the docs) and a 'Not for' exclusion list (background polling, page traversal, opaque byte interpretation, combat validation). This tells an agent both when to pick this tool and when to avoid it, which is exactly the guidance dimension this rubric rewards.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, but the description goes well beyond them: it discloses that the read is a POST, that no reward, delivery or grant is created, that MIGRATION_REQUIRED preserves legacy originals and never authorizes a replacement, and it maps the 409/401/403/429/ACHIEVEMENT_NOT_MANUAL failure modes to concrete recovery actions. Rate-limit and auth-source behavior are both covered.

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 with the core action and then labeled blocks (Use when / Not for / Requires / Side effects / Returns / Errors) that make skimming easy. The errors paragraph is dense and partially redundant with the auth block, so it is slightly longer than it needs to be, but every section carries operational information.

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?

No output schema exists, yet the description supplies the return shape ({achievements,results:[{key,state,inboxEntryId,code}]}) and interprets edge cases (compact achievements have no Inbox ID). Combined with error handling, side effects and auth prerequisites, an agent has everything needed to call and interpret this correctly.

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 100%, so the baseline is 3. The description adds genuine meaning on top: it explains where sessionToken comes from (the accessToken of a prior sign-in) and ties userId to the signed-in player ('pass the userId that signed in' on a 403), and it reinforces the fixed one-to-eight key bound and the 'never invent a replacement key' rule for retries.

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: 'Reads compatibility reward status for up to eight original achievement keys.' It draws a hard boundary against the achievement siblings with 'Not for: delivering or claiming new achievement rewards; new unlocks credit immediately,' which separates it from horizon_unlock_achievement and horizon_get_achievements. It also implicitly corrects the misleading 'deliver' in the tool name.

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' (diagnosing an older unsettled reward without changing its original identity) and explicit 'Not for' (delivering or claiming new rewards). Prerequisites are spelled out: sign in via horizon_signin_email or horizon_signin_anonymous and pass its accessToken as sessionToken, plus the HORIZON_API_KEY requirement. Nothing about when to reach for this versus a sibling is left to inference.

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

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

Goes well beyond the annotations: it discloses permanence and non-replayability, that no recipient receipt is added, that only one HTTP attempt is made, that the response replaces only the matching host/project/player cache, and it maps 409/404/422/401/403/429 to concrete meanings and remedies. The 'one HTTP attempt only' and rate-limit notes are the kind of operational detail annotations cannot express.

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?

Well front-loaded and labeled (purpose, Use when, Not for, Requires, Side effects, Returns, Errors), so an agent can scan to the section it needs. It is long and the error enumeration is dense with mixed concerns (auth, rate limits, validation) that could be trimmed, but almost every sentence carries actionable information.

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 destructive, revision-guarded mutation with no output schema, the description covers everything an agent needs: the auth prerequisite and token plumbing, exact-revision semantics, permanence, the full return shape, and per-status recovery rules. Nothing essential to calling it correctly or recovering from failure is left unstated.

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 still adds real meaning by tying expectedRevision to the reviewed revision ('never refresh and substitute automatically'), pinning instanceId to an exact owned instance from reviewed inventory, and explaining that sessionToken comes from horizon_signin_email/horizon_signin_anonymous and must be sent as a Bearer token. That exceeds what the schema's field descriptions convey.

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 ('Discards Item') and immediately narrows the scope ('Permanently removes this instance'), so the agent knows this is a destructive inventory mutation rather than a read or an adjustment. It never names its nearest siblings (horizon_adjust_item, horizon_equip_item, horizon_get_items as the read counterpart), so differentiation is only inferable from behavior rather than stated.

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 'Use when' / 'Not for' pair is explicit and unusually useful, ruling out automatic retries and revision-forcing, which is exactly where an agent would otherwise go wrong. It also names horizon_get_items as the reconciliation path after a 409 or uncertain response. The positive condition ('the player explicitly requests this inventory action') is somewhat generic, but the exclusions carry the guidance.

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

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

Annotations declare the safety profile (destructive, openWorld, idempotent), and the description adds substantial context beyond them: the write is limited to the equipped boolean and does not enforce slot rules, it makes exactly one HTTP attempt, the returned inventory shape and cache-replacement rule, plus a full error taxonomy (409/404/422/401/403/429) with prescribed recovery rather than silent retry. The idempotentHint and 'one attempt only' detail are complementary rather than contradictory given the expectedRevision guard.

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?

Labeled sections (Use when / Not for / Requires / Side effects / Returns / Errors) make a long block scannable and front-load the routing decision. It is dense but nearly every sentence carries actionable information; only the duplicated 401/rate-limit diagnostics edge toward verbosity.

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 mutating, open-world, revision-guarded tool with no output schema, it covers prerequisites (API key, session flow), side-effect scope, the returned inventory shape, and every foreseeable failure with recovery guidance. Nothing needed to invoke it correctly is missing.

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 real meaning on top by explaining how sessionToken is obtained (horizon_signin_email/horizon_signin_anonymous accessToken), that userId must match the signed-in session, and that expectedRevision must be the exact reviewed revision with no silent refresh. It stops short of documenting the equipped/instanceId semantics beyond what the schema already says.

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+resource (set an item instance's equipped boolean) and the precondition that makes it distinct: it operates on an exact reviewed inventory revision and instance UUID, unlike horizon_adjust_item or horizon_discard_item. An agent can distinguish it from its inventory siblings without opening any 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' (player explicitly requests the inventory action) and 'Not for' (automatic retries, client grants, forcing through by swapping revision/instance IDs). It also routes to the concrete alternative for the uncertain case (horizon_get_items to reconcile intent), satisfying the when/when-not/alternatives bar.

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

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

Annotations already mark this as read-only and idempotent, and the description reinforces that with 'Side effects: Read only' and 'No game state is returned.' It adds substantial context beyond annotations: auth requirements, candidate/result limits, cursor semantics, rate limits, and a detailed error taxonomy.

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 long but well structured and front-loaded: purpose first, then use/not-for guidance, prerequisites, side effects, return shape, and errors. The error section is dense and somewhat expansive, but it remains relevant to correct invocation and troubleshooting.

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 fully documents the return shape as {matches,nextCursor,pollAfterSeconds,serverTime}. It also covers auth, read-only behavior, pagination limits, valid empty pages, and relevant error paths, making it complete for this complex tool.

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 useful meaning by linking sessionToken to the accessToken from sign-in and requiring userId to match the signed-in player. It also frames minStrength and maxStrength as a strength-filtered lobby query, though those parameters are still mostly explained by the schema.

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: it reads one strength-filtered open-lobby page under current blocks and active-owner checks. That distinguishes it from broader match retrieval siblings such as horizon_get_matches and horizon_get_match.

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 gives a 'Use when' condition tied to asynchronous multiplayer actions after reading the matches docs, and a 'Not for' list covering polling, page traversal, timeout progression, invented winners, and automatic rewards. It also directs reconciliation with horizon_get_matches and horizon_get_match.

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

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

The annotations already declare a read-only, idempotent, non-destructive, open-world operation, and the description usefully adds 'Side effects: None', the return shape, auth prerequisites, and 401/403/429 handling. However, the long error section is contaminated with unrelated mutation/friend-request/inbox/revision-conflict behavior, which is misleading context for a simple player lookup.

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, usage, auth, side effects, and return shape are front-loaded and clearly labeled, but the description is bloated by a large error block that mostly describes unrelated friend-request, inbox, and revision-conflict flows. Many sentences do not earn their place for this read-only lookup tool.

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 3-parameter read-only lookup with full schema coverage and rich annotations, the description includes the important missing pieces: auth acquisition, query form, return shape, and relevant 401/403/429 behavior. Its completeness is undermined by irrelevant and potentially confusing error cases such as 409 REVISION_CONFLICT, FRIEND_REQUEST_NOT_FOUND, and INBOX_FULL.

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 schema already documents the three parameters well. The description still adds value by clarifying that query is exact UUID or canonical H-code and by explaining that sessionToken is the accessToken from horizon_signin_email or horizon_signin_anonymous, and that userId must match the signed-in player.

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 verb and resource: finds one public player by exact UUID or canonical H- friend code in this project. It also clearly scopes the tool away from email/name search, enumeration, and presence testing, which distinguishes it from nearby player/friend tools.

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 gives explicit when-to-use guidance (player intentionally shares ID or friend code) and explicit when-not-to-use cases (email/name search, enumerating players, testing online presence). It also names sign-in alternatives for obtaining the required session token.

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

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

The description goes well beyond the annotations by specifying authentication prerequisites, sign-in alternatives, no side effects and no granting behavior, response shape, cache scoping, cache retention semantics, and detailed error handling including 401, 403, 409, 429, ACHIEVEMENT_NOT_MANUAL, and MIGRATION_REQUIRED. The read-only claims are fully consistent with readOnlyHint=true and destructiveHint=false.

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 and uses helpful labels such as Use when, Not for, Requires, Side effects, Returns, and Errors. It is information-dense but long, with some highly implementation-specific sentences about compact progress and legacy settlement that are useful but reduce conciseness.

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 complex read operation with no output schema, the description supplies the return shape, auth requirements, cache behavior, side-effect guarantees, and detailed failure modes. Nothing critical for correct invocation appears to be missing.

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 100%, so the schema already documents userId, sessionToken, and definitionVersion. The description reinforces the userId/sessionToken relationship and names horizon_signin_email and horizon_signin_anonymous as sources for the accessToken, but it does not meaningfully elaborate on definitionVersion beyond the schema.

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 gives a specific verb and resource: reads visible achievement definitions and permanent completion bits. It also distinguishes the operation from mutations and hidden-achievement revelation with explicit 'Not for' language, so an agent can separate it from related achievement and statistics tools.

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 clear usage contexts: loading progress or refreshing after newlyUnlocked statistics or realtime invalidation, and explicitly excludes changing balances and revealing locked hidden achievements. It does not name the best alternative for those excluded cases, such as horizon_unlock_achievement or horizon_get_statistics, which keeps it below a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds genuinely new behavioral context: the required HORIZON_API_KEY, the isError/HTTP-status error contract, a 401 meaning a bad key, and a 429 per-minute rate limit with retry guidance. This is exactly the auth-needs and rate-limit disclosure that goes beyond structured annotations.

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-loads the purpose, then uses labeled sections (Use when / Not for / Side effects / Returns / Errors) that map to the questions an agent asks before calling. Every sentence carries information; the only mild redundancy is the read-only side-effect line, which is negligible.

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?

Given an output schema exists, return-shape explanation is optional, but the description goes further by covering auth, empty-result behavior (total 0), and error/rate-limit semantics. Nothing an agent needs to invoke this read tool correctly is missing.

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 100%; the lang parameter is fully documented in the schema (ISO 639-1, 2 lowercase letters, enumerated values, omit for default). The description restates 'one language' and the default-language fallback but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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 ('Reads all translated strings of one language as a key to text map') and immediately scopes it with the default-language behavior. It explicitly distinguishes itself from the single-key sibling horizon_get_localization, so an agent can select between them without opening either 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?

Provides an explicit 'Use when' (game start or language switch, load all UI text at once) and an explicit 'Not for' that names the alternative (horizon_get_localization) for single keys. Both the positive trigger and the exclusion are stated, leaving nothing to inference.

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

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

Annotations already declare readOnly/idempotent/destructive/openWorld, but the description goes well beyond them by disclosing auth requirements (HORIZON_API_KEY), the error contract (isError with HTTP status/body), and behavioral specifics for 401 (key wrong) and 429 (per-minute rate limit; wait and retry). This is rich operational context the annotations cannot provide.

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 with the operation, then cleanly labeled sections (Use when, Not for, Side effects, Returns, Errors). Every sentence adds distinct value; nothing is padding.

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?

An output schema exists, yet the description still orients the agent on the {configs, total} shape and the empty-map/zero-total edge case, plus the full error taxonomy. For a read-only config fetch, an agent has everything needed to call and interpret it.

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?

The tool takes zero parameters, so there is no parameter semantics to document; the description's 'key to string map' phrasing correctly conveys the shape of what is read. Baseline 4 applies for a parameterless tool.

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 (reads) and resource (every remote config value of the app) with clear scope (all, in one call, as a key-to-string map). It distinguishes itself from siblings by naming horizon_get_remote_config for single values, so an agent can route correctly without opening schemas.

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' (game start, to cache all flags at once) and 'Not for' clauses that route to two named alternatives: horizon_get_remote_config for a single value and horizon_test_connection for API-key checks. Nothing is left to inference.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description still adds real behavioral context: read-only even under FREE/mute/ban, no polling timer, and a full error contract (404 channel hiding, 409 reconciliation requirement, 429 no auto-retry, 501 NOT_SUPPORTED, 401 re-auth, 403 userId mismatch). The rule "Never replace an unknown send UUID/time/text" is a genuine safety constraint not derivable from structured fields.

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 when/when-not/auth/returns blocks are front-loaded and scannable, but the error paragraph sprawls into one dense run-on covering 404/409/429/501/401/403/API-key/rate-limit cases. Several clauses (the horizon_test_connection cross-reference, the restated 429 meaning) repeat earlier statements and dilute the signal for a read-only introspection tool.

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?

No output schema exists, so the description carries the return shape itself ({limits,capabilities,moderation,serverTime}), the auth prerequisite chain, and the failure semantics. Nothing an agent needs to call this correctly on the first attempt is missing.

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 goes further by explaining provenance — sign in via horizon_signin_email/anonymous and pass the resulting accessToken as sessionToken, with userId matching that signer. That is meaningfully more than the schema's "Player accessToken sent only as Bearer".

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?

"Reads five-tier bounds, current moderation and hosted capabilities" gives a specific verb and a concrete set of resources, and the Returns line enumerates the payload. The phrase "five-tier bounds" is a bit of internal jargon, but combined with the return keys the agent can tell this is a limits/capability introspection call, distinct from horizon_send_chat_message and horizon_get_chat_operation.

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" / "Not for" structure with concrete exclusions (automatic sends, repeated polling, rich-text rendering, exposing moderation credentials). It names the alternatives and the ordering: horizon_get_chat_operation to reconcile an original send, then horizon_send_chat_message for the identical replay only.

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

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

Beyond readOnly/idempotent/openWorld annotations, the description discloses the critical nuance that a missing or expired receipt does not prove a send never committed and cannot authorize a new ID, and that no historical per-player copy is retained. It also documents the error surface (404 masking private/missing/expired, 409 OPERATION_CONFLICT/EXPIRED and STATE_CONFLICT, 429 non-retry, 501 NOT_SUPPORTED, 401 vs 403 session semantics) and the HORIZON_API_KEY requirement.

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?

Well front-loaded with labeled sections (Use when / Not for / Requires / Side effects / Returns / Errors), so an agent can scan to the relevant part. It is however quite long for a read tool, and the trailing paragraph re-explains 401/429 already covered in the Errors line, which is mild redundancy rather than a structural flaw.

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 3-parameter read with no output schema, the description supplies auth prerequisites, the return shape ({receipt, serverTime}, metadata only), the side-effect/retention model, and a full error-to-cause mapping. Nothing an agent needs to invoke this correctly, or to interpret a failure without retrying blindly, is missing.

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 real meaning: sessionToken must come from the signin tool's accessToken, and userId must be the identity that signed in ('pass the userId that signed in'). It also frames operationId as the original canonical UUID that must never be replaced when unknown, which the schema alone does not convey.

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 opening sentence gives a specific verb and resource ('Reads the current player's retained original send receipt'), which is precise enough to separate it from siblings like horizon_get_chat_limits or horizon_get_marketplace_operation. Scope ('current player', 'retained original') is stated up front, so an agent knows exactly what object is being fetched.

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 hosted chat actions after reading horizon://docs/chat) and 'Not for' clauses (automatic sends, repeated polling, rich-text rendering, exposing moderation credentials) give both sides of the decision. It also names the follow-up alternative, horizon_send_chat_message, and restricts it to 'explicit identical replay', plus points to horizon_signin_email/horizon_signin_anonymous for prerequisite auth.

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

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

Annotations already cover readOnly/idempotent/destructive, but the description adds substantial context beyond them: auth requirement (HORIZON_API_KEY), rate-limit behavior (429 per-minute, wait and retry), 401 meaning, and cross-API-key id rejection. These are genuine behavioral disclosures the annotations do not provide.

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?

Uses labeled sections (Use when / Not for / Requires / Side effects / Returns / Errors) with the purpose front-loaded, so scanning is fast. It is somewhat verbose, and restating the return fields is arguably redundant given an output schema exists, but no sentence is wasted.

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 single-parameter read tool this covers everything an agent needs: selection criteria, prerequisites, side-effect profile, error taxonomy with remediation, and return shape. Output schema exists, yet the description's return summary is a harmless supplement rather than a gap.

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% and the schema already documents emailId as the UUID returned by horizon_send_email, so the baseline is 3. The description adds that an unknown id or one belonging to another API key is rejected, which is a real invocation constraint beyond the schema text.

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 ('Returns the delivery status... of one email queued with horizon_send_email') and enumerates the possible status values. It explicitly distinguishes itself from the siblings horizon_send_email and horizon_cancel_email, so an agent can select it without ambiguity.

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?

Provides explicit when-to-use ('checking whether a sent or scheduled email was delivered, or why it failed') and when-not-to-use with named alternatives ('Not for: sending again... or stopping delivery...'). This is the full when/when-not/alternative triple.

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

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

Beyond the read-only/idempotent annotations, the description explains snapshot replacement semantics, the meaning of lastActiveAt, revision-conflict recovery, request-not-found behavior, inbox/capacity limits, auth failures, API-key failures, and rate-limit behavior. This is unusually rich behavior detail for an agent invoking the tool.

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 and sectioned into use cases, exclusions, requirements, side effects, return shape, and errors. Despite its length, the structure makes every part easy to scan and the detail is justified by the missing output schema and numerous failure modes.

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?

With no output schema, the description compensates by describing the complete returned snapshot fields. It also covers auth acquisition, cache replacement, online-presence semantics, and key error recovery paths, leaving little an agent needs to infer before calling it.

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 already 100%, so the schema documents userId and sessionToken format. The description still adds meaningful operational semantics: userId must match the signed-in player, and sessionToken must come from one of the horizon_signin_* tools as the accessToken.

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 read operation and enumerates exactly what is read: friends, incoming/outgoing requests, blocks, and limits. It also distinguishes itself from nearby social mutations and explicitly rules out online-presence polling, so an agent can identify its role among siblings.

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 gives explicit positive triggers (opening a social screen, reconciling an uncertain mutation) and explicit exclusions (polling for online presence, applying old snapshots to a new session). The auth prerequisite also points to the exact sign-in tools whose token should be used.

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

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

Goes well beyond annotations by describing the return shape, auth prerequisites, error/status semantics, rate-limit behavior, and the rule against automatic retry. It also clarifies that failures return isError with HTTP status and body.

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?

It is front-loaded and clearly labeled (Use when, Not for, Requires, Returns, Errors), but the error paragraph is very long and partly redundant, especially around 429 and 401 handling. For a single-group read, the description is overstuffed relative to its core purpose.

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?

No output schema exists, so the description supplies the return shape and member/nonmember visibility rules. It also covers auth, side effects, and error reconciliation, making it complete enough for correct invocation.

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 useful meaning by explaining how to obtain sessionToken via horizon_signin_email or horizon_signin_anonymous and by tying userId to the signed-in Bearer session.

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 ('Reads group') and clarifies scope with 'Not for: unbounded group search', which distinguishes it from horizon_get_groups. The return note ('GroupView: public metadata for nonmembers, with data/myRole only for members') confirms it is a single-group read.

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?

Explicitly gives 'Use when' and 'Not for' conditions, including exclusions around unbounded search and stale snapshots. The error section also names horizon_get_groups and horizon_get_group_pending as alternatives for reconciliation.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, and the description adds substantial context beyond that: no side effects, page-size constraints, revision-conflict handling, 401/403/429 semantics, and rollback behavior for related pending actions. It does not contradict the annotations.

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 long but well structured with labels like "Use when", "Not for", "Requires", "Returns", and "Errors", and the core purpose is front-loaded. Some error and auth details are repeated, but most sentences add operational value for a complex authenticated paginated read.

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 carries return-value documentation and does so explicitly: groupId, revision, members, nextAfterUserId, and serverTime. It also covers pagination, revision conflicts, auth failures, and rate limits, making it complete enough for correct invocation.

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 schema already documents the parameters. The description adds useful meaning for authentication semantics: userId must match the signed-in player, sessionToken is the accessToken from a sign-in tool, and limit must not exceed current memberPageSize.

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 verb and resource: "Reads group members using a matching player session." It also distinguishes scope with explicit exclusions for unbounded group search, automatic pagination, and stale snapshots, so an agent can tell this apart from broader group-reading or reconciliation tools.

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 gives explicit "Use when" and "Not for" guidance, and names alternatives such as horizon_get_groups and horizon_get_group_pending for reconciliation. It also explains the required sign-in flow and session-token dependency, leaving little to inference.

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

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

Goes well beyond annotations: states side effects are none, requires leader/officer membership, describes the return payload, and maps error codes (409 REVISION_CONFLICT, 403, 429, 401, INBOX_FULL rollback) to required agent behavior. The value is real, but the 'Use horizon_get_groups and horizon_get_group_pending to reconcile state' line is self-referential and slightly misleads about recovery paths.

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 labeled (Use when / Not for / Requires / Side effects / Returns / Errors), which makes the long error catalogue scannable. Slightly overlong and repetitive — the 429 no-automatic-retry rule is stated twice — and the self-referential recovery line costs it 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 read tool with no output schema it supplies the return shape ({groupId,revision,invitations,joinRequests,serverTime}), the retained-entries guarantee, auth requirements, and error semantics, so an agent could invoke it correctly. Residual gaps are minor: the revision-conflict reconciliation guidance is ambiguous about which sibling actually performs the reconciliation.

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, and the description earns an extra point by synthesizing the parameters into an auth story: sign in via horizon_signin_email/horizon_signin_anonymous, pass the accessToken as sessionToken, and pass the userId that signed in. It also clarifies 403/token-mismatch failure modes for those 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 ('Reads group pending requests') plus the session precondition, which is enough to place it alongside horizon_get_groups and horizon_get_group. It loses a point because the Errors paragraph confusingly names the tool itself ('horizon_get_groups and horizon_get_group_pending') as the thing to reconcile with, muddying the sibling boundary.

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?

Uses explicit Use when / Not for framing: 'opening a group screen or reconciling an uncertain action' versus 'unbounded group search, automatic pagination or using stale snapshots after a session change.' It also names prerequisites (leader/officer membership, session signin) so the agent knows when it cannot use this tool at all.

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

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

Beyond the read-only/idempotent annotations, it discloses required auth flow, return contents, rate-limit behavior, session-expiry handling, conflict semantics, and API-key dependency. It also clarifies that failures return isError with HTTP status and body.

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 and labeled well, but it is long and the error section repeats 401/403/429 details and includes action-oriented errors like INBOX_FULL and original requestId reconciliation that are not clearly relevant to a read-only groups fetch.

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?

Because there is no output schema, the description usefully explains that MyGroupsView includes memberships, pending invitations/requests, revision, limits, and serverTime. It also covers auth, side effects, and error handling sufficiently for an agent to invoke the tool correctly.

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 real workflow meaning: sign in first, pass accessToken as sessionToken, and pass the userId that signed in when the session belongs to another user. That goes beyond the schema's field descriptions.

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 verb and resource: reads 'my groups' using a matching player session. It clearly distinguishes this list-my-groups operation from unbounded search, pagination, and stale-snapshot use, and it routes reconciliation to the pending-groups sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.