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 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?

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?

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?

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/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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so safety is covered structurally. The description adds useful non-annotation context: no session token required, the userId provenance, error semantics (404/401/429 with the 429 rate-limit wait-and-retry instruction), and the isError behavior. That said, much of the return-shape detail is redundant with the existing output schema, so it does not reach the top of the range.

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 front-load the scope before the alternative routing. It is slightly long, and the Returns block partially duplicates the output schema, 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?

Given a read-only tool with a full schema and an output schema, the definition still covers prerequisites (userId, no session token), auth (HORIZON_API_KEY), error handling and rate-limit recovery, and the sibling routing needed to call it correctly. Nothing an agent needs 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%, so all three parameters (range, userId, leaderboardKey) are already documented, including UUID format and the leaderboardKey pattern/default. The description echoes the userId source and leaderboardKey default rather than adding new semantics 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 ('returns the leaderboard entries directly above and below a player's own position') and immediately distinguishes itself from horizon_get_leaderboard_top and horizon_get_user_rank. An agent can identify the exact scope 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' gives the triggering scenario ('you and your rivals' UI) and 'Not for' names both alternative siblings with the condition that selects each. 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?

Goes well beyond annotations: discloses the self-entry append behavior when the userId is outside the list, empty-board behavior, 404/401/429 error semantics with remediation, the HORIZON_API_KEY requirement, and 'no session token'. The read-only claim aligns with readOnlyHint.

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 a labeled structure (Use when / Not for / Requires / Side effects / Returns / Errors) that makes scanning trivial. Every sentence carries operational value with no 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?

Covers return shape, edge cases (empty board, self-entry), auth prerequisites, and error taxonomy including cross-tool 401 comparison. Despite an output schema existing, the extra edge-case detail is warranted and complete 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% and both userId and leaderboardKey carry full descriptions including UUID format, defaults, and the 'omit to use the API key's default board' fallback. The description largely defers to the schema, which is the right call here, so 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+resource ('Returns the top entries of a leaderboard from position 1') and explicitly distinguishes from siblings horizon_get_user_rank and horizon_get_leaderboard_around. An agent can pick the right 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' (global top list, top 10/top 100) and 'Not for' clauses naming the two alternative tools and their selecting conditions. 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?

Goes well beyond the annotations (which only cover readOnly/idempotent/destructive/openWorld) by disclosing the return shape, that a missing key is NOT an error (found=false, value=null), the HORIZON_API_KEY requirement, and the 401/429 failure semantics including rate-limit 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?

Front-loaded with the core action, then clearly labelled Use when / Not for / Side effects / Returns / Errors sections. Dense but 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?

Despite the output schema existing, the description completes the picture by covering the auth prerequisite, non-error missing-key case, and error taxonomy, which the schema and annotations do not convey.

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 both parameters are already documented in the schema. The description only restates the default-language behavior for 'lang', adding no syntax beyond the structured fields; 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 one translated string by key in one language') plus the default behavior, which an agent can distinguish immediately from horizon_get_all_localizations and horizon_get_localization_languages.

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' with a concrete example (dynamic message) and an explicit 'Not for' clause naming both alternative tools and the conditions that select them.

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 readOnly/idempotent/non-destructive annotations, the description adds auth requirements (HORIZON_API_KEY), the exact return shape ({languages, total} with ISO 639-1 codes, empty when no translations), and concrete failure semantics including distinguishing 401 from horizon_test_connection and the 429 per-minute rate limit with a retry hint.

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?

Organized as labeled, front-loaded sections (Use when / Not for / Side effects / Returns / Errors) with no filler. The only mild overlap is the Returns section against the existing output schema, but it is brief and non-redundant in substance.

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 zero-parameter read tool, the definition covers routing, semantics, side effects, return structure and error behavior, so an agent can select and invoke it without further exploration. Nothing needed is missing given the annotations and output schema already 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?

The tool takes zero parameters, so the schema baseline applies (baseline 4). There is nothing for the description to clarify about inputs, and it correctly adds no invented parameter 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?

States a specific verb+resource ('Lists the languages that have at least one translation for the app') and immediately bounds the scope to translated languages only. It is clearly distinguishable from horizon_get_localization and horizon_get_all_localizations, which return texts rather than the language list.

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 says when to use ('before horizon_get_localization or horizon_get_all_localizations, to pick a valid lang or build a language menu') and when not ('the texts themselves - use horizon_get_all_localizations'). Alternatives are named with the condition that selects them.

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 by disclosing auth requirements (HORIZON_API_KEY), filtering behavior (only published entries past release date), empty-array semantics, and detailed error semantics: 401 means a bad key (cross-referenced to horizon_test_connection) and 429 means a per-minute rate limit with a retry instruction. This is exactly the extra context annotations don't 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?

Front-loaded with purpose, then cleanly labeled sections (Use when / Not for / Side effects / Returns / Errors). The length is justified because each section carries decision-relevant information for an agent with no output schema to fall back on.

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 specifying the return shape ({id, title, message, releaseDate, languageCode}), field semantics, and empty-result meaning. Auth, side effects, and error handling are all covered, so an agent has everything needed to invoke and interpret the 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 coverage is 100%, so the baseline is 3. The description reinforces the languageCode filtering meaning ('optionally filtered to the player's language', all languages when omitted), which adds contextual clarity, though it adds no syntax detail for limit beyond what the schema already documents.

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 ('Lists the published in-game news... announcements, patch notes'), adds ordering ('newest first'), and explicitly distinguishes itself from siblings horizon_get_remote_config and horizon_get_localization. An agent can identify the tool's scope 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' condition (a game shows a news feed or message of the day, optionally language-filtered) and an explicit 'Not for' with the correct alternative named for each exclusion. 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 declare readOnly/idempotent/non-destructive, yet the description goes further: it names the required session flow (signin tools producing accessToken), the no-side-effects guarantee, the HORIZON_API_KEY dependency, per-minute 429 rate limits, and specific error semantics (401/403/404) with remediation. This is materially richer than 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-loaded with labeled sections (Use when/Not for/Requires/Side effects/Returns/Errors) that make it highly scannable. The Errors paragraph is verbose with some redundancy, but nearly 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?

Though an output schema exists, the description still enumerates the return shape and the meaning of the 'available' flag, covers auth prerequisites, side-effect profile, and the full error/rate-limit surface. Nothing an agent needs 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 description coverage is 100%, so both parameters (userId UUID, sessionToken) are already documented in the schema. The description restates their provenance (userId from signup/signin, sessionToken as Bearer) but adds little 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+resource ('Returns a player's profile ... unlocks and the cosmetics catalog') and explicitly distinguishes itself from horizon_set_profile and from leaderboard-embedded profiles. An agent can identify this tool's scope without reading any other 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 'Use when' (before horizon_set_profile, to show the selection screen), 'Not for' (changing the profile, showing others' profiles), and names the correct alternatives for each excluded case. 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 declare readOnly/idempotent/non-destructive, but the description goes well beyond them: unknown keys are not errors (found=false, configValue=null, fall back to a default), all values are strings requiring manual parsing, and error semantics include HORIZON_API_KEY requirement, 401 diagnosis via horizon_test_connection, and 429 per-minute rate limit with a wait-and-retry instruction.

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 organized under labeled sections (Use when / Not for / Side effects / Returns / Errors), with the core purpose front-loaded in the opening sentence. Every line carries actionable information; none is 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?

For a one-parameter read with an output schema, the description supplies everything an agent needs: auth requirement, verbatim error taxonomy, string-typed return caveat, and default-fallback behavior on missing keys. Nothing material is omitted.

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 single 'key' parameter is fully documented in the schema (case-sensitivity, 256 char max, example). The description adds only 'by key', contributing nothing beyond the structured field, 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?

Specific verb+resource ('Reads one remote config value by key') with scope stated as a single value, and it explicitly contrasts with the sibling horizon_get_all_remote_configs. An agent can distinguish these two tools 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?

Explicit 'Use when' (single value / check one feature flag) and 'Not for' (loading many values at start → use horizon_get_all_remote_configs, one request instead of many), naming the exact alternative and the condition that selects it.

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, and the description still adds substantial context beyond them: required session token sourcing, the UTC-day reset semantics of earnedToday, the 0-when-never-earned default, the empty-values case, and a full error taxonomy (401/403/404/429) with remediation. This is far richer than the annotation baseline.

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 purpose and organized under clear labels (Use when / Not for / Requires / Side effects / Returns / Errors), which aids scanning. It is on the long side and the Returns section overlaps the output schema, but for a tool with this many auth and error paths the length is largely earned.

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 complexity of session-authenticated reads with specific error codes, the description covers prerequisites, side-effect profile, return shape semantics, and failure handling. Even though an output schema exists, the added day/dailyCap/sorting semantics make it complete 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 description coverage is 100%, so userId and sessionToken are already documented in the schema; the description's 'Requires: userId and the player's session' largely restates that. It adds only the constraint that the session must come from a matching sign-in, which is marginal value over 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?

Opens with a specific verb+resource ('Returns the player's server-owned values (Validated Actions)') and enumerates the concrete payload (balance, today's earnings, daily cap). It explicitly names siblings it is not (horizon_submit_validated, horizon_load_cloud_data), so an agent can separate it from the many horizon_* 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?

Provides an explicit 'Use when' trigger (wallet display, pre-spend check), an explicit 'Not for' exclusion with the correct alternative named for each case (horizon_submit_validated for writes, horizon_load_cloud_data for saves). Nothing about 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description goes beyond them by disclosing required auth (HORIZON_API_KEY), the 404 semantics (no score yet / unknown board) with remedies, and 401/429 failure handling including rate-limit advice. This is substantial behavioral context an agent cannot get from 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?

Labeled sections (Use when / Not for / Requires / Side effects / Returns / Errors) make it scannable and front-loaded with the core purpose first. The Errors sentence is dense and long, but each clause is actionable 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?

Although an output schema exists, the description still summarizes the return shape and profile sub-fields, and it covers auth, error taxonomy, and rate limits. Nothing an agent needs to select or invoke this 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%, so both userId and leaderboardKey are fully documented in the schema (origin, format, default-board behavior). The description largely restates those origins rather than adding new syntax or value constraints, so the baseline 3 is correct.

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 ('Returns one player's own position, score and profile on a leaderboard') and immediately distinguishes itself from the sibling list tools by scope (single player's own rank vs. a list of entries). An agent can differentiate it from horizon_get_leaderboard_top/around 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?

Gives explicit 'Use when' triggers (after horizon_submit_score, to show 'your rank') and an explicit 'Not for' with named alternatives (horizon_get_leaderboard_top, horizon_get_leaderboard_around). Preconditions are also spelled out (needs a userId, no 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?

Annotations already declare readOnly/idempotent/non-destructive, so the description's 'Side effects: None (read only)' is redundant. It earns credit for the downstream-key contract ('pass a key as leaderboardKey... without it they use the default board') and the validatedOnly semantics, but the errors section partially overlaps with the output schema and general MCP error patterns.

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 Use/Not-for/Side effects/Returns/Errors sections. Dense but well-organized. The errors paragraph names a specific 401/429 interplay with horizon_test_connection that is useful, though slightly verbose.

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, the return values needn't be restated, yet the description does so anyway (helpful for agents that don't parse schemas). The auth/error contract (HORIZON_API_KEY, 401/429 semantics, test_connection cross-reference) fills a real gap for a zero-param read 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?

Zero parameters, so baseline is 4. The description adds value by explaining how returned keys are consumed by other tools, which is param-adjacent semantics not present in the (empty) 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?

Specific verb+resource ('Lists the leaderboard boards of this API key') with the returned fields enumerated, and sibling tools for reading entries are named as out-of-scope. An agent can distinguish this discovery/listing tool from horizon_get_leaderboard_top 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?

Explicit 'Use when' clauses (multiple boards, before submitting to learn leaderboardKey/validatedOnly) plus an explicit 'Not for' clause naming the three alternative tools for reading entries. This is the strongest form of routing 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 already declare readOnly/idempotent/non-destructive, and the description adds layers beyond them: the auth prerequisite (sign in via horizon_signin_email/anonymous, pass accessToken as sessionToken), HORIZON_API_KEY requirement, the normal-case 'found:false/saveData:null' semantics, and error decoding (401 expired session, 403 token-user mismatch, 429 rate limit). This is unusually rich behavioral disclosure that directly shapes correct invocation and retry logic.

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 purpose followed by labeled sections (Use when / Not for / Requires / Side effects / Returns / Errors). It is dense, but every sentence carries actionable detail — auth, edge cases, error triage — with no 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?

Given the tool is a read with an output schema, the description needn't explain return shape, yet it still documents the found/saveData contract and first-run initialization. Combined with auth, side-effect, and error coverage, 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 baseline is 3, but the description adds practical meaning: where userId and sessionToken come from, the sign-in flow that produces the token, and the 403 rule that the userId must match the signed-in user. That goes beyond the schema text, though it doesn't fully specify field formats.

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: 'Reads a player's save game that was stored with horizon_save_cloud_data.' It ties the resource to the exact sibling that produces it, and the paired 'Not for' clause names the write counterpart, so an agent can distinguish it 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 triggering conditions ('when the game starts or the player switches devices') and explicit exclusions routing to alternatives ('use horizon_save_cloud_data' for writing, 'horizon_get_state' for server-owned balances). Covers both when-to-use and when-not-to-use.

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 (readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false) only sketch the safety profile; the description adds far more: one redemption is consumed per success, the action cannot be undone, repeat calls redeem again or fail at the per-player limit, unlock grants mutate the player's unlocks, HORIZON_API_KEY is required, and per-minute rate limits apply. It also spells out the full error taxonomy (404, 400 expired/revoked/limit, 409 UNLOCK_LIMIT_REACHED with the code not consumed, 401 vs 403 semantics) and the isError result 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?

Densely labeled with 'Use when', 'Not for', 'Requires', 'Side effects', 'Returns', 'Errors', and front-loads the core action and its cost before the detail. Every section carries actionable content, though the error enumeration is long enough that an agent must read past several lines to reach the auth/rate-limit notes.

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 fully specifies the return shape ({success, message, giftData, grantedUnlocks}), explains that giftData is a JSON string the game must parse and apply, and clarifies that grantedUnlocks lists post-redemption cosmetic IDs. Combined with auth prerequisites, side effects, and error handling, an agent has everything needed to invoke and interpret this 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 code, userId, and sessionToken are already documented at the field level, including that the token is sent as a Bearer session. The description restates the acquisition path ('sign in with horizon_signin_email or horizon_signin_anonymous and pass its accessToken as sessionToken') but adds no format, constraint, or edge-case detail beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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?

Starts with a specific verb+resource ('Redeems a gift code for a player') and immediately scopes what the call does: consumes a redemption and returns reward data plus cosmetic unlocks. It explicitly names the sibling it is not (horizon_validate_gift_code), so an agent can distinguish redeem from validate 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 explicit when ('the player confirms a code in the game'), when-not ('only checking a code'), and the alternative (horizon_validate_gift_code, noted as using nothing up). The routing decision between redeem and validate is fully specified with the cost trade-off that motivates it.

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 goes well beyond them: it explains what gets destroyed (the single save slot, old save gone), that re-saving is a no-op, the auth prerequisites (userId + sessionToken from sign-in), and enumerated error meanings (403 tier limit, 401 expired session, 429 rate limit, wrong API key).

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 in the first sentence, then labels blocks (Use when / Not for / Requires / Side effects / Returns / Errors). Despite its length, every section carries actionable information an agent needs, with no 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?

No output schema exists, and the description compensates fully by documenting the return shape ({success, dataSizeBytes}) and the full failure surface with status codes and remediation. Auth, side effects, and limits are all covered, leaving no material gap for a mutation 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: data is usually serialized JSON subject to a lower tier limit than the schema maxLength, and sessionToken is the accessToken from a specific sign-in tool that must belong to the passed userId. This relationships-and-provenance detail is not 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 (Stores) and resource (a player's save game as one string) with scope: it replaces the previous save. Explicitly distinguishes itself from horizon_load_cloud_data and the Validated Actions siblings, so an agent can select it 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?

Uses explicit 'Use when' and 'Not for' framing, names the alternative read tool (horizon_load_cloud_data) and the server-owned-currency alternative (horizon_submit_validated/horizon_get_state). The condition that selects each sibling is 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 cover the safety profile (readOnlyHint=false, idempotentHint=false, openWorldHint=true), and the description adds substantial context beyond them: it queues one email per call, repeating sends again (so never retry a status check), requires an SMTP config + dashboard template + verified recipient, and documents the return shape and the 400/401/429 error semantics including rate limiting.

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?

Purpose is front-loaded, followed by labeled Use when / Not for / Requires / Side effects / Returns / Errors blocks, so an agent can scan to the relevant section. It is long, but the length is justified by the non-idempotent send and multiple error modes; little of it is 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?

No output schema exists, and the description compensates fully by describing the return object ({id, status, scheduledAt}), how to use the id downstream, the required credentials (HORIZON_API_KEY), and the error envelope behavior. Everything needed to call the tool correctly 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, but the description adds failure semantics tied to specific parameters: a 400 for an unknown templateSlug or a recipient without a verified email address, plus the instruction to check the slug in the dashboard or pick another user. That is genuine meaning beyond the schema field docs, though most syntax still lives 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+resource+scope: 'Queues a transactional email from a dashboard template to one registered player, sent now or at a scheduled time through the developer's own SMTP server.' It also distinguishes itself from siblings by name (horizon_get_email_status, horizon_cancel_email), so an agent can route correctly 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' (game triggers a message to a player) and 'Not for' clauses that name the two alternative tools for delivery checking and cancellation. When-to-use, when-not-to-use, and alternatives are all stated rather than inferred.

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=true and idempotent=true, the description goes well beyond them: it explains that omitted/null/empty clears slots, that the call replaces all three slots at once, the catalog/type/unlock constraints, the 3-badge cap, the leaderboard visibility, and a full error taxonomy (400 INVALID_BADGES, 403 COSMETIC_LOCKED, 401/403 SESSION_*, 404, 429 rate limit with retry advice). This is unusually rich disclosure and 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?

Long but dense and well-sectioned into Use when / Not for / Requires / Side effects / Returns / Errors, with the destructive replace-all semantics front-loaded. Every sentence carries actionable content, though the error-code enumeration makes it heavier than strictly necessary.

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?

A mutation tool with no output schema needs to explain side effects, auth, and failure modes; it does all three, including what is returned (the get_profile body) and the isError contract. Nothing an agent needs to call this 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, but the description adds real meaning: pass current values from horizon_get_profile for slots that should stay, every ID must belong to the API key's catalog with the type of its slot and be free or unlocked, and at most 3 distinct badges. These constraints are semantic rules not expressible in the JSON 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?

Opens with a specific verb and resource ("Sets a player's avatar, frame and displayed badges") and immediately names the sibling it is not (horizon_get_profile for reading). An agent can distinguish it from the ~30 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?

Explicit "Use when: the player confirms a new look" plus a concrete instruction to seed unchanged slots from horizon_get_profile, and a "Not for:" clause naming the alternative. Both the when and the when-not are 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?

The annotations already mark this as a non-read-only, non-idempotent, non-destructive, open-world operation. The description goes well beyond them by disclosing session side effects, token lifetime, rate limits, required API key, and error semantics, all 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?

The description is well structured with front-loaded sections for use, exclusions, requirements, side effects, returns, and errors. It is somewhat verbose, however, and the 429 explanation is repeated in the final sentence, slightly diluting 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 one-parameter authentication tool with no output schema, the description covers prerequisites, returns, session lifetime, side effects, and common failure modes. An agent has enough information to invoke it correctly and handle expected 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 description coverage is 100%, so the input schema already fully documents anonymousToken, including its exact format and origin. The description adds only a light reminder that the token comes from horizon_signup_anonymous for this account, without extra syntax or usage detail 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 states a specific verb and resource: signs in an anonymous guest account and starts a player session. It distinguishes itself from siblings by naming horizon_signin_email and horizon_signup_anonymous as adjacent but different 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?

It explicitly says when to use it ('returning guest opens the game', 'right after horizon_signup_anonymous') and when not to use it, naming both alternative tools. The routing guidance is complete enough that an agent can choose correctly without opening other schemas.

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 behavior far beyond the annotations: a new session is created on every call while older sessions stay valid, token lifetime of one hour after last use, HORIZON_API_KEY requirement, 401/403 discrimination, isError semantics on every failure, and the 429 per-minute rate limit. This is a model example of documenting side effects and auth needs.

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 organized into labeled Use when/Not for/Side effects/Returns/Errors blocks. It is long but dense and well-structured; a few clauses (e.g. the dual-401 explanation) could be tightened, keeping it just short of perfect.

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 non-idempotent, open-world auth tool with no output schema, the description covers purpose, gating, side effects, returned fields, token lifecycle, error codes, and rate limiting. An agent has everything needed to call it and handle outcomes.

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 email and password constraints are already fully documented in the schema. The description only restates that email and password are used and adds post-call guidance (pass userId/accessToken as sessionToken), which is about return usage rather than parameter meaning. 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+resource ('Signs in an existing email account with email and password and starts a player session'), and goes further by naming the return token. It clearly delineates itself from the signup/anonymous/check 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?

Explicit 'Use when' clause (registered, verified player logs in before any sessionToken-dependent tool) plus a 'Not for' clause that names the exact alternative for each rejected case (horizon_signin_anonymous, horizon_signup_email, horizon_check_auth). 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?

Adds substantial context beyond the annotations: one account created per call with no lookup semantics, no session started, the anonymousToken being the only way back in, the need for HORIZON_API_KEY, and per-status error handling (400/401/429). The annotations already cover non-idempotence and open-world behavior, and the description reinforces and extends that with the retry and storage 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?

Dense but well partitioned into Use when / Not for / Side effects / Returns / Errors, with the core purpose front-loaded. Every labeled sentence carries unique operational value (idempotence caveat, token storage, error triage) rather than repeating structured fields.

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 enumerates the return object fields and the follow-up call (horizon_signin_anonymous) needed for a session. For a low-complexity, 1-param signup tool this leaves no meaningful 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%, so the single displayName parameter (with its 30-char limit) is fully documented by the schema. The description reinforces that only a display name is needed and adds the 400-invalid-name failure mode, but adds no syntax 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 ('Creates a new anonymous (guest) player account') plus the exact return artifact ('returns its anonymousToken'). It explicitly distinguishes itself from the email-signup and returning-guest siblings, so an agent can route correctly 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' clauses name the alternatives (horizon_signup_email, horizon_signin_anonymous with stored token) and the selecting condition (no email / first guest launch). 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?

Adds rich context beyond annotations: account starts unverified/no session, sends a verification email, does not sign in, and it documents error semantics (409, 400, 401, 429) plus required HORIZON_API_KEY. This is far beyond the minimal readOnly/destructive/idempotent 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?

Front-loaded purpose, then structured 'Use when/Not for/Side effects/Returns/Errors' blocks. Well organized, though the error block is dense and could be trimmed slightly.

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 no output schema and a mutation tool, the description fully covers return value (userId, isVerified:false), side effects, follow-up workflow, and error handling. Nothing an agent needs to invoke 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%, so the schema already documents email/password/displayName constraints. The description restates some password length limits but adds little new semantic detail beyond the schema's baseline.

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?

Specific verb+resource ('Creates a new player account') with scope details ('starts unverified and without a session'). Explicitly distinguishes from siblings horizon_signin_email and horizon_signup_anonymous.

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' for new email registrations and 'Not for' naming the two alternatives (signin, anonymous signup). Also gives a follow-up flow when email is already taken.

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 (non-read-only, non-idempotent, open-world) cover only the safety profile; the description adds the real behavior: a new single-use ticket per call, run limits per player and per account, ticket expiry, server-owned start values bound into the run, and a full error taxonomy with stable codes and remediation for each (401/403/404/429/503). This is well beyond what the annotations 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?

Roughly 350 words, but front-loaded with the core action and then segmented into Use when / Not for / Requires / Side effects / Returns / Errors labels, which makes it scannable. It loses a point for mild redundancy, e.g. 429 handling appearing both in the Errors list and again in the closing rate-limit note.

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 return object is enumerated and the follow-through workflow is spelled out (seed deterministic randomness with seed, record the input log, submit with horizon_submit_validated using the unchanged ticket before expiresAt). Nothing needed to call this 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 and the schema already documents all nine parameters. The description nonetheless adds semantics not in the schema, notably that leaderboardKey binds the ticket to a board that must already exist and that 'default' is created on first use, plus how the optional context fields are consumed server-side.

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 and mechanism: 'Starts a server-checked run (Validated Actions): issues a single-use ticket with a server seed and starts the server's run timer.' It distinguishes itself from siblings by explicitly naming horizon_submit_score and horizon_get_state as the wrong tools for adjacent needs.

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' (before a round whose score or currency must be server-checked; always for boards marked validatedOnly in horizon_list_leaderboards) and explicit 'Not for' with the correct alternatives named. Prerequisites and auth chain 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?

Although annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description adds substantial context beyond them: one entry per call with duplicates on repeat, the literal 'ok' return, required HORIZON_API_KEY, 403 feedback-limit behavior, and a full error taxonomy including 401 vs 429 diagnosis. This is rich, actionable behavioral disclosure 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?

Labeled sections (Use when / Not for / Requires / Side effects / Returns / Errors) make it highly scannable, and the core purpose is front-loaded. Despite its length, each block carries distinct operational information an agent needs.

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 non-idempotent mutation tool with no output schema, the description covers auth requirements, side effects, the return value, and the full failure surface including status-code interpretation. 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 description coverage is 100%, so the schema already documents all six parameters with formats and length limits. The description reinforces userId provenance (from horizon_signup_*/horizon_signin_*) and the session-token-free requirement, but adds little semantic detail the schema lacks. Baseline 3 is appropriate.

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 ('Sends a message written by a player ... to the developer's feedback inbox') and enumerates the content types (bug report, feature request, comment). It explicitly names the siblings it is not, so an agent can distinguish it from horizon_create_crash_report and horizon_create_log 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?

Provides an explicit 'Use when' (player fills in a feedback/bug report form) and an explicit 'Not for' with the two alternative tools named for each excluded case. The condition selecting each sibling is spelled out, 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 by disclosing the replace-only-if-better semantics, the auth/session flow, the return value, and a full error taxonomy (403 VALIDATED_SUBMIT_REQUIRED, 403 PLAYER_BANNED, 404, 401, 429) with retry guidance. This is exactly the extra context annotations (idempotentHint=true) 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?

Front-loaded with purpose and organized under labeled clauses (Use when / Not for / Requires / Side effects / Returns / Errors), so it scans well. It is on the long side, but nearly every clause carries actionable content 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?

No output schema exists, yet the description supplies the return shape and the full error/retry matrix, plus the session prerequisite. An agent has everything needed to invoke correctly and handle failures without consulting anything else.

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 meaning by explaining how sessionToken is obtained (horizon_signin_email/anonymous) and that leaderboardKey can be omitted to use the API key's default board. It doesn't add format detail beyond the schema, but the auth-flow framing is genuinely 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?

States a specific verb+resource ('Submits a player's score to a leaderboard') and immediately disambiguates by board type ('higher on DESC boards, lower on ASC boards'). It clearly distinguishes itself from horizon_submit_validated and the read-oriented 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?

Provides explicit 'Use when', 'Not for', and 'Requires' sections, naming the alternative tools (horizon_start_run + horizon_submit_validated for validated boards, horizon_get_leaderboard_top for reads). The trigger condition (round ends on a normal board) is unambiguous.

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?

Far exceeds the annotations (destructiveHint/readOnlyHint/idempotentHint/openWorldHint): it discloses single-use ticket consumption even on rejection, which error classes spend vs. preserve the ticket, the soft-threshold 'sus' flag and review package, dailyCap/maxBalance clamping semantics (credited < requested), the concurrent-spend race where credited==0, and the 24h evidence-upload obligation. This is exactly the behavioral 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?

Very long, but structured with labeled sections (Use when / Not for / Requires / Side effects / Returns / Errors) and front-loaded with the purpose before the routing rules. Given 10 parameters, a stateful ticket lifecycle and dozens of error codes, nearly every sentence earns its place, though some error-code enumeration 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?

With no output schema, the description carries the full return-value burden and does so thoroughly: the response object fields, the meaning of sus, the null state/evidence cases, credited-vs-requested clamping, and the retryability of each HTTP status. Nothing an agent needs to call and interpret this 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 coverage is already 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: the log itself is never sent and a hash-only log must be retained by the caller, exactly one of the three log inputs is required, and earned positive/negative amounts map to earn/spend with clamping implications. Score required only when a board is targeted is reinforced with the ignore case.

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 ('Submits the result of a run started with horizon_start_run') and the server-side validation it triggers. It explicitly distinguishes itself from horizon_submit_score (runs without a ticket) and horizon_get_state (reading balances), so an agent can route without opening a schema.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

Has explicit 'Use when', 'Not for' and 'Requires' sections that name the alternatives (horizon_submit_score, horizon_get_state, horizon_signin_*, horizon_upload_evidence) and the exact conditions selecting them. The lifecycle is unambiguous: a validated run ends, send ticket + score + log commitment.

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 (which already declare readOnly, idempotent, open-world and non-destructive), the description discloses the required env vars, the exact failure semantics (401 means bad key, 429 means per-minute rate limit, network error means bad base URL), and the default URL. This is materially more than the annotations 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-structured and front-loaded with labelled sections (Use when / Not for / Side effects / Returns / Errors) so the agent can scan quickly. It is slightly verbose in the Errors block and repeats the read-only fact already implied by Side effects, so it falls short of maximum 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?

Even with an output schema present, the description supplies the auth prerequisite, the success/failure interpretation, and the meaning of key error codes. For a first-run diagnostic in a crowded 33-tool namespace, 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?

The tool takes zero parameters, so the baseline is 4. The description reinforces this with 'takes no input', but there is nothing further to document at the parameter level.

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 ('Checks that HORIZON_API_KEY and HORIZON_BASE_URL reach the horizOn API by fetching the app's remote configs') and explicitly marks it as a no-input diagnostic. It also distinguishes itself from the two nearest siblings, so the agent can select it 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?

Gives explicit timing ('first during setup, and whenever other tools fail'), the diagnostic intent ('tell a configuration problem from a problem of the call itself'), and named alternatives for the cases it is not for (horizon_check_auth, horizon_get_all_remote_configs). 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 only declare the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false); the description goes well beyond them, disclosing auth prerequisites (signin + accessToken as sessionToken, HORIZON_API_KEY), the one-upload-per-run limit (409), size cap (maxBytes 32,768), rate limiting (429), and a full enumerated error table with retry-worthiness classification. That is exactly the behavioral 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?

Front-loaded and organized with clear Use when / Not for / Requires / Side effects / Returns / Errors sections, so the agent can scan to what it needs. It is dense and the closing paragraph restates the 401 and 429 semantics already implied above, which is minor redundancy rather than bloat.

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 supplies the return shape ({runId, status, bytes, inputLogHash}) and its comparison purpose. Combined with prerequisites, limits, side effects, and error handling, an agent has everything needed to invoke 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 coverage is 100%, so the baseline is 3, but the description adds real semantics: the mutual exclusivity of inputLog/inputLogBase64, the requirement that the uploaded bytes' SHA-256 equal the submit's inputLogHash, where each token originates, and a 32,768-byte effective cap that differs from the schema's maxLength. It does not need to do more since the schema documents each field.

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 ('Uploads the input log of a validated run') and ties it directly to the producing sibling (horizon_submit_validated with evidence.required = true). An agent can distinguish it from submit tools and from unrelated uploads 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' (only after a submit result carries evidence.required: true, before evidence.uploadBefore/24h) and 'Not for' clauses that name the failure the server returns (404 EVIDENCE_NOT_REQUESTED) and the alternative pattern (passing the log with the submit, which only takes a hash). 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 read-only/idempotent/non-destructive, but the description adds genuinely new behavioral context: no redemption is consumed, no session token is required, the exact error contract (isError with HTTP status/body), how to interpret a 401 vs horizon_test_connection, and 429 rate-limit retry handling. This goes well beyond 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?

Uses labeled sections (Use when / Not for / Requires / Side effects / Returns / Errors) that are strongly front-loaded and skimmable. Despite its length, every sentence carries actionable content with no 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?

Covers prerequisites (userId source), auth requirements (HORIZON_API_KEY), side-effect profile, return interpretation, and error handling. An output schema exists so return details are a bonus rather than a requirement, and the description still clarifies the critical valid=false case.

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% and both parameters are already documented in the schema (including the UUID format, pattern, and signup/signin origin). The description restates the userId origin and adds that no session token is needed, but provides no new per-parameter syntax, 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 ('checks whether...can be redeemed') and resource (gift code), plus explicit scope ('without using it up'). Explicitly distinguishes itself from horizon_redeem_gift_code, so an agent can pick it apart from its sibling 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 explicit 'Use when' (before redemption, to confirm a typed code and surface errors early) and 'Not for' (claiming the reward; validating grants nothing) guidance, naming the alternative tool directly. 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.