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

Annotations only indicate readOnlyHint=false and destructiveHint=false, so the description carries the behavioral burden. It discloses that entries are public, requires game ownership, explains that version labels are unique per game, and notes that omitting version auto-increments the last one. This is meaningful context beyond the annotations, though it does not discuss auth or error conditions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action in the first sentence, then efficiently covers usage triggers, content style, an alternative route, and version behavior. Each sentence contributes distinct information without padding or restating the 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 four-parameter tool with full schema coverage and no output schema, the description provides everything needed to call it correctly: ownership requirement, content expectations, optional persona handling, version behavior, and a delegation path to upload_game_build. No critical call-time information is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds value for the `body` parameter by instructing player-centric wording rather than commit-style language, and for `version` by clarifying it is free text, unique per game, and auto-incremented when omitted. The `game` and `persona` parameters are already well explained by the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Writes a public changelog entry on a game you own.' It distinguishes from sibling tools like update_changelog_entry, delete_changelog_entry, and list_changelog by framing this as the additive create operation, and the 'public' and 'you own' constraints further narrow the scope.

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

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

It explicitly states when to use the tool: whenever a player-loaded game is different from yesterday, with concrete examples like 'a new build, a rebalanced level, a bug you closed.' It also names a clear alternative: if pushing a new single-file build, pass `changelog` to upload_game_build instead, which does both in one 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?

With no readOnly/idempotent/destructive hints, the description carries the behavioral burden and does so well: it discloses magic-number validation, CDN storage, supported formats, the 5MB limit, and append ordering. It doesn't cover failure modes or idempotency, but the disclosed side effects are sufficient for a safe call.

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?

Five compact sentences front-load the purpose and then add only high-value operational details. No filler or repetition of schema descriptions.

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 4-param, no-output-schema mutation tool with no annotations, the description covers input selection, format constraints, ordering behavior, and the alt-text requirement. An agent has everything needed to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: exactly one of url/base64 is required, the https requirement and data URL acceptability, format/size limits, and the strong directive to always write alt text. This is substantial value 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?

Describes a specific action ('Adds one screenshot'), resource ('a game you own'), and a key constraint ('up to 6 per game'). This clearly differentiates from sibling tools like remove_screenshot, reorder_screenshots, and set_cover.

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?

States that screenshots are appended in call order and explicitly names reorder_screenshots as the alternative for changing order, which is concrete usage guidance. It does not explicitly contrast with remove_screenshot or set_cover, but the ownership and upload context implies when this tool applies.

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 only provide false hints (not read-only, not idempotent, not destructive), so the description carries the behavioral disclosure burden. It adds meaningful non-obvious behaviors: creation always lands as a draft, the slug is minted from the title, and the slug never changes because links outlive titles. This is valuable beyond what the schema reveals, though response format is not disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact: four sentences, front-loaded with the core action and draft status, followed by a scannable pipeline. Every sentence contributes useful information; there is no filler or restatement of schema details.

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 11 richly documented parameters and minimal annotations, the description covers the critical gaps: draft semantics, slug immutability, and the intended workflow. The main omission is the absence of an output schema and any description of the response shape, so the agent must infer that the created game's identifier is returned for subsequent update/build calls.

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 input schema describes all 11 parameters at 100% coverage, which sets a baseline of 3. The description adds value beyond the schema by clarifying that only title is required and, more importantly, that the slug is derived from the title and is immutable. That extra semantic link justifies a score above 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?

The description opens with a specific verb and resource: 'Creates a game on your account.' It further differentiates from siblings by stating the result always lands as a draft and that publishing is a separate act, so an agent can immediately tell create_game apart from publish_game and update_game.

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

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

The description gives clear usage context: only title is required, the game is always created as a draft, and publishing is deliberately separate. The typical flow (create_game → upload_game_build → define_achievements → add_screenshot → set_cover → publish_game) is explicit guidance. It does not name update_game as the alternative for existing games, but the boundary is strongly implied.

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

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

The description goes well beyond the minimal annotations (readOnlyHint false, destructiveHint false). It discloses key behavioral traits: creator visibility to moderators, per-account bans/rate limits/vote counting, the 5-persona cap, shared username namespace, and the permanent-link breakage on rename. This is rich, actionable context that annotations alone 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?

The description is front-loaded with purpose, then use case, then critical policy and namespace constraints, then the rename warning. Every sentence contributes new, decision-relevant information; there is no filler or repetition of schema content. Though dense, it remains focused and well organized.

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 creation tool with no output schema and only basic annotations, this description supplies all the context needed to invoke it correctly: purpose, limits, visibility, namespace constraints, rename implications, and the sibling that handles modifications. Nothing essential for correct selection or invocation 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 bio, username, avatarUrl, and displayName fully. The description adds meaningful semantic context beyond the schema by explaining the username namespace ('shares one namespace with every other persona and account'), the near-permanence of the username, and recommending update_persona for avatar uploads. This earns above the baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear verb and resource: 'Creates another public identity you can publish under.' It then gives concrete, specific use cases (a series, a genre, a character) that immediately distinguish it from update_persona and list_personas. No ambiguity about what the tool does.

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

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

It explicitly states when to use one ('when a body of work deserves its own shelf') and when not to ('rather than for evading anything'). It also routes to the alternative update_persona for later changes and for avatar byte uploads, which is exactly the kind of sibling differentiation an agent needs.

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

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

The description provides rich behavioral context: owner-only maker data, game-code integration with Arcade.achievements.unlock(), idempotency on (game, slug), preservation of earned counts, and a 100-per-game cap. However, it directly contradicts the annotation idempotentHint=false by declaring 'This tool is idempotent on (game, slug)'. Per the scoring rule, a contradiction with annotations forces a score of 1.

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 four purposeful sentences with the core behavior front-loaded, followed by ownership/security context, idempotency, sibling routing, and the hard limit. Every sentence earns its place and there is 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?

For a 9-parameter tool with no output schema, the description covers most operational essentials: ownership, game-side code contract, overwrite behavior, idempotent retry safety, batch alternative, and maximum count. It loses a point because the idempotency claim is contradicted by the idempotentHint=false annotation, making the behavioral picture unreliable, and no return-value information is provided.

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 documents all nine parameters, including guidance for slug, name, hidden, points, and description. The tool description adds contextual limits and idempotency, but no per-parameter semantics beyond what the schema already provides, 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?

The description opens with a specific verb and resource: 'Adds one achievement to a game you own, or overwrites the one that already has this slug.' It clearly distinguishes this single-achievement upsert from the plural define_achievements tool and from update/delete alternatives.

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

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

It explicitly states the ownership precondition, explains when the tool is safe for publish scripts, names the alternative define_achievements for batch declaration, and gives the max-per-game limit. This is actionable routing guidance, not just a vague hint.

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

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

The description directly contradicts the annotation idempotentHint=false: it promises 're-running your publish script changes nothing,' which is an explicit idempotent upsert claim. Per rubric, a description that contradicts annotations receives a 1 here, even though the surrounding behavioral detail (ordering, partial failure, no deletion) is otherwise excellent.

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 dense but every sentence earns its place, front-loading the main purpose and build-pipeline context before moving into failure semantics and non-deletion guarantees. There is no redundant expansion of schema fields and 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?

For a batch mutation with no output schema, the description covers prerequisites, ordering, the 100-entry cap, partial-failure behavior, recovery guidance, and the deletion path. An agent has everything needed to invoke this tool correctly and recover from failures.

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 goes well beyond the schema: it explains that slugs must match Arcade.achievements.unlock() exactly, that anything else is refused, that entries apply in order, and that an oversized set fails at the first non-fitting entry. These are semantics an agent cannot derive from the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('batch form of define_achievement'), states the exact key behavior ('upserts every entry on (game, slug)'), and distinguishes itself from the single-achievement sibling. It is immediately clear what this tool does and how it differs from define_achievement.

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 says explicitly when to reach for this tool ('when you publish'), gives a concrete pipeline position ('create_game → upload_game_build → define_achievements → add_screenshot → set_cover → publish_game'), and names the alternative for retiring achievements ('use delete_achievement'). The usage context is fully actionable.

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 destructiveHint annotation by disclosing that every unlock is deleted from every player's trophy case, the count won't return even if the slug is re-declared later, and that this cascade is intentional.

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 longer than average, but the length is justified by the irreversible destructive behavior. The core action is front-loaded and the warnings and alternatives are relevant. The 'Read this part twice' instruction is slightly extra but acceptable.

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 the operation, the irreversible cascade, the reason behind it, the correct alternative, and the follow-up action needed in client code. With rich annotations and full schema coverage, nothing necessary for correct selection or invocation 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%, and both parameters are already documented with examples and constraints. The description adds context about slug reuse but does not need to repeat parameter details.

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: 'Removes one achievement from a game you own.' It also distinguishes itself from update_achievement by clarifying that deletion is for removing a badge, not fixing wording.

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 this tool vs update_achievement, warns that this is the destructive call in the set, and advises removing unlock calls in code to avoid NOT_FOUND errors. This is model 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 indicate destructive behavior via destructiveHint=true and idempotentHint=false. The description adds meaningful nuance by stating the deletion is permanent and leaves no tombstone, which goes beyond what the annotation flags alone would tell an agent.

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?

Three short, purposeful sentences. The destructive semantics are front-loaded, followed by use-case guidance and the alternative routing. Every sentence earns its place 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?

For a tool with one fully documented parameter, clear destructive annotations, and no output schema, the description provides everything needed to select and invoke the tool correctly. It covers what, why, when, and which sibling to prefer instead.

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 input schema fully documents the single parameter entryId with its source ('from list_changelog'). The description does not add parameter-level meaning beyond the schema, so a baseline score of 3 is appropriate given the high schema coverage.

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 ('Deletes'), a specific resource ('changelog entry'), and the key behavioral distinction ('outright — no tombstone, nothing left on the page'). It also clearly differentiates from update_changelog_entry, so an agent knows exactly what this tool does.

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

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

Explicitly names the scenarios for use ('wrong game or wrong version number') and the preferred alternative when those conditions do not apply ('Prefer update_changelog_entry when the entry is right and its wording is wrong'). This is strong 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 only mark destructiveHint=true, but the description adds significant context: the conditional delete-vs-delist behavior, the rationale about preserving user contributions, and the fact that the response distinguishes which action occurred. This is exactly the kind of nuance an agent 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?

The description is compact and well-structured: first sentence states the core behavior, second explains the critical exception and rationale, third tells the agent what the response reveals. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having no output schema, the description covers the key ambiguity (published vs unpublished) and tells the agent the response distinguishes the two outcomes. Given the single well-documented parameter and rich annotations, nothing essential 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 input schema already covers the single parameter thoroughly, including format (slug or uuid) and an example. The description adds no parameter-specific meaning, but the schema coverage is 100%, 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 ('Deletes a game') and immediately clarifies the conditional scope by publish status. This clearly distinguishes it from the sibling delist_game by explaining when deletion happens and when delisting happens.

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 clear behavioral context: it tells the agent what happens for unpublished vs published games and that the response indicates the outcome. It does not explicitly compare against the delist_game sibling, but the described behavior makes the usage boundary 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?

Beyond the destructiveHint annotation, the description explains the specific behavioral outcomes: the public page 404s, the game disappears from search and the sitemap, and the record, votes, and comments are retained. This clarifies exactly what 'destructive' means and, importantly, what is not destroyed.

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 three compact sentences with no filler. The core behavior is front-loaded in the first sentence, and the follow-up sentences efficiently add the public-facing consequences and the alternative-tool guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter mutation tool with a destructive hint, the description covers the public effect, the preservation of underlying data, and the relationship to delete_game. Nothing essential for an agent to select and 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?

The schema fully documents the single parameter, including that it accepts a slug or a uuid. The tool description does not add parameter-specific detail, so the schema carries the weight; the baseline 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?

The description states a specific action ('Retires a game from the public site'), the exact resource, and the resulting observable behavior: the page 404s, leaves search, and leaves the sitemap. It also distinguishes itself from delete_game, so an agent can differentiate the tool 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?

The description explicitly says to use this tool rather than delete_game for anything that has been live. That is a clear when-to-use instruction and identifies the main alternative. It also implies that delete_game is for cases where delisting is not appropriate, giving useful decision 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 cover read-only, idempotent, non-destructive behavior, so the description does not need to restate safety. It adds the useful ownership scoping ('one game you own') and the polling use case, but it does not disclose return format, freshness guarantees, or rate-limit behavior. The description adds some behavioral context, but not richly enough to go above 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?

The description is two focused sentences with no filler. It front-loads the substantive metric list and then adds a practical polling rationale. Every sentence contributes useful 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?

The output schema is absent, so the description must communicate what the tool returns. It does this thoroughly by enumerating the metric categories. It doesn't describe the exact response shape or any time-window semantics, but the listed fields are enough for an agent to understand and use the result.

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 game parameter is already well documented as a slug or uuid. The description adds the context that the game must be owned by the caller, but it doesn't add format or syntax detail beyond the schema. Baseline 3 is appropriate because the schema carries the explanatory weight.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the exact resource and scope: 'The numbers for one game you own.' It then lists a specific set of metrics (upvotes/downvotes, net score, plays, views, comments counts, bug report statuses), which clearly separates this from generic metadata getters like get_game and collection tools like list_my_games.

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

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

The description states the intended usage directly: 'This is the read to poll if you want to know whether a change helped.' This provides a clear when-to-use signal for monitoring the impact of an update. It does not explicitly mention alternatives or when not to use it, but the context is strong enough for an agent to make the right 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 readOnly, idempotent, and non-destructive. The description adds useful behavior beyond that: API-key-free access for published games and key-dependent visibility for drafts/delisted games. This is meaningful contextual behavior not inferable from the schema.

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?

Two compact sentences: the first front-loads the operation and output contents, the second covers the auth behavior. Every sentence carries useful information with no filler or restating of the title.

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 having no output schema, the description enumerates the key response contents and the auth-dependent visibility behavior. For a single-parameter read-only tool, this is sufficient for an agent to select and 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 coverage is 100% and the only parameter, 'game', already documents slug or id in the schema. The description repeats this but adds no new format, constraints, or edge-case details, so it meets the baseline without exceeding it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource: it fetches one game by slug or id, and enumerates the exact set of returned data (description, play mode, URLs, tags, AI tools, counts, status, screenshots). It is clearly distinguished from search/list siblings because it targets a single known game.

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 implies the right context: use this when you need complete details for a specific game identified by slug or id. It also provides auth guidance (published games need no key; drafts/delisted games require your key), but it does not explicitly name alternatives or say when not to use 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 readOnlyHint=true and idempotentHint=true, so the description correctly confirms this is a safe read without contradiction. It adds meaningful context beyond the annotations by explaining the significance of `unlockCount` and how to use it to identify an unreachable badge, which is not present in any structured field.

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?

Two sentences with no wasted words, but the second sentence is dense with both a usage instruction and a data-analysis hint. It front-loads the purpose and return fields, which is good, though the sentence could be split for readability. Still, it earns its length.

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 fully enumerates all returned fields and provides a practical use case for the `unlockCount` field. For a simple one-parameter read tool, this is complete. The 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?

The schema has 100% coverage of the single `game` parameter, providing a clear description of slug or id. The description adds no additional parameter semantics, but given the complete schema, a baseline of 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?

The description clearly states the tool lists achievements defined on a game, enumerating the exact fields returned (slug, name, description, emoji, points, hidden, unlockCount). It distinguishes itself from sibling tools like define_achievement or update_achievement by framing it as a read operation on the existing badge 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?

The description explicitly advises reading this before touching a game's badge set, implying it is a prerequisite for any modification tool. However, it doesn't name specific alternatives or state when not to use it, leaving some inference to the agent. The context is clear enough for most cases.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the tool is known to be safe and non-mutating. The description adds the default ordering behavior ('open reports first') and notes that status changes are visible to the reporter (via update_bug_status). However, it doesn't disclose pagination or error behavior. With annotations covering the safety profile, the description adds moderate extra context, warranting a 3.

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?

Three short sentences, front-loaded with the core purpose. The first sentence states what the tool does and default ordering; the second gives a usage tip; the third explains the pairing workflow. No filler or redundancy. The structure is efficient and easy to parse.

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 simple list tool with documented parameters and no output schema, the description is mostly complete but lacks an explicit statement of what the response contains (e.g., fields like title, description, status). It also doesn't mention pagination, though the schema covers perPage. Given the tool's simplicity, the description is adequate but not fully complete for an agent that might need to know the response shape.

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 all four parameters are documented. The description adds a hint that status filtering is useful for backlog work, which gives a use-case context to the status parameter. It does not add syntax or format details beyond the schema. Given full schema coverage, a baseline 3 is appropriate, with slight credit for the status-filter context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'list' and the resource 'bug reports', and adds context: 'The bug queue for your game, open reports first.' This distinguishes it from other list tools like list_changelog or list_comments, and even from the sibling update_bug_status which mutates status. The resource and scope are unambiguous.

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

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

The description gives explicit guidance on when to filter by status ('when you are working through a backlog') and directly pairs with update_bug_status, explaining the workflow (fix, ship, mark fixed). It doesn't explicitly state when not to use this tool, but the pairing and context make the intended usage clear. Slight deduction for no mention of alternatives beyond the paired tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds the display-order detail and the dependency linkage to game publishing, which is meaningful behavioral context beyond the annotations. It lacks return format details, but given the simple list nature and annotation coverage, this is sufficient.

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?

Two concise sentences with no filler. The core purpose ('category list, in display order') is front-loaded, followed by practical usage context. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a parameterless, read-only, idempotent list tool, the description provides essential context: the display ordering and its role in game creation. It doesn't detail the return structure, but given the simplicity and that annotations cover safety, the definition is complete enough for an agent to call 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?

The tool has zero parameters, so the description need not explain parameter meanings. The baseline of 4 is appropriate because there is nothing to compensate for, and the description does not include any irrelevant parameter-related text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists categories in display order and connects it to the need for a valid categorySlug when publishing games. It differentiates by implying this is the source for valid slugs, distinguishing it from other list tools like list_changelog or list_my_games.

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 instructs to call this before create_game and warns against guessing the categorySlug. This provides clear when-to-use guidance and implicitly steers away from hardcoding slugs, making the usage context 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?

Annotations already mark this as read-only and idempotent, and the description adds useful behavior beyond that: it works without an API key for published games, applies to any visible game, and orders entries so the latest is where work resumes. This adds meaningful context not present in 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?

Two sentences deliver the purpose, scope, auth behavior, and a practical usage tip with no filler. The key definition is front-loaded, and the guidance earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter read-only tool, the description covers what the tool returns, the scope of access, authentication requirements, and when to call it. No output schema exists, but the description sufficiently explains the return contents.

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 single parameter is fully documented in the schema, including the accepted formats of slug or uuid. The description adds minimal semantic value beyond the schema, so the baseline score of 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?

The description clearly states a specific verb and resource: listing a changelog, and elaborates on what that means (change history, timestamps, version labels, build status). It also distinguishes itself from the changelog mutation siblings by being the read-facing counterpart.

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

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

The description gives concrete guidance on when to use the tool, notably before modifying a game that hasn't been shipped to in a while, and notes the last entry is the starting point for the next version. It doesn't explicitly enumerate alternatives like add_changelog_entry, but the read-vs-write distinction is clear from context and sibling names.

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/destructive annotations, the description discloses ordering (newest root comment first, replies flat beneath), the meaning of parentId, and the ownership-dependent visibility of hidden comments. This adds real behavioral context that annotations alone 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?

Three dense sentences, with the core purpose and ordering front-loaded and the ownership distinction following naturally. Every sentence contributes either behavioral detail or usage context; there is 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?

For a read-only list tool with strong annotations and a fully described schema, the description covers ordering, reply nesting, ownership, hidden-comment behavior, and even the follow-up action of posting a reply. 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?

The input schema already documents all four parameters with 100% coverage, so the baseline is 3. The description adds meaning by framing `includeHidden` in terms of the maker's inbox and by explaining how the public thread is used to choose a parentId for post_comment, going slightly beyond the schema's literal descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource (comments) and a specific action (list), then sharpens the scope by distinguishing the maker's inbox on owned games from the public thread on other games. It also points to the comment structure via parentId, making it easy to tell this apart from post_comment.

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

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

It gives clear situational guidance: use this on your own game for the maker's inbox, and on others for the public thread, with includeHidden explicitly scoped to owned games. It relates the tool to post_comment by noting this is where you pick a parentId, though it does not explicitly enumerate when not to use it versus other sibling tools.

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 establish this is read-only, idempotent, and non-destructive. The description adds useful behavioral detail: it includes drafts and delisted entries, sorts newest first, and signals that the output contains id and slug values. It stops short of describing full response structure or pagination, but the annotations lower the burden.

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?

Two sentences, no filler. The most important scoping information is front-loaded ('whole catalogue, newest first'), followed by inclusion caveats and a concrete purpose. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only list tool with no required parameters and fully documented inputs, the description is complete. It tells the agent what the tool returns (game identifiers), when to use it, and how it differs from search; the annotations confirm it is safe.

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 documentation covers both parameters completely (limit range and includeUnpublished semantics). The description reinforces that the tool returns identifiers, but it does not add meaningful parameter-level information beyond what the schema already provides, so the baseline score 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?

The description names a specific action and resource: list the user's whole catalogue. It adds concrete scope ('including drafts and delisted entries that never appear in search') and states the ordering ('newest first'), which clearly distinguishes it from search_games and get_game.

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

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

It gives a clear use case: 'Use it to find the id or slug you need for the other tools.' It also implies when not to rely on search, since hidden entries 'never appear in search.' It does not explicitly name an alternative for public-only or keyword-driven lookups, but enough context is provided.

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?

It reveals non-obvious behavior beyond the read-only annotations: personas are publicly unlinked from the account, each has its own /u/ page showing only its own games and comments, and votes belong to the account rather than the persona. This is substantial contextual value that 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?

Three sentences cover the concept, public-page behavior, downstream usage, default behavior, and vote semantics with no filler. It is slightly concept-heavy rather than verb-led, but every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter read-only list, the description covers what personas are, how to consume them, and important account-level semantics. It does not spell out the response shape or whether a default persona is included, but the tool's complexity is low and annotations already cover the safety profile.

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 has zero parameters, so the baseline of 4 applies. The description adds relevant context about the `persona` argument on sibling tools, though it documents no parameters for this tool itself.

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 title and description clearly identify the resource as 'your personas,' and the phrase 'Pass any of these to the persona argument' implies the tool returns the set of personas. However, the description never states an explicit verb like 'lists' or 'returns,' and it does not explicitly distinguish itself from sibling persona 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?

The description gives concrete downstream context: returned personas can be passed to the `persona` argument on create_game, update_game, post_comment, or report_bug, and omitting it publishes as the default. It does not explicitly contrast with alternatives like whoami or set_default_persona, but the usage context is clear.

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

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

Beyond the generic annotations, the description reveals important behavioral traits: the comment is public, it appears under a persona byline, threading is limited to one level, and low-quality or spam-like comments may be reported. This adds substantial practical context that annotations alone do not 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?

The description is compact and front-loaded with the core purpose, then moves to reply mechanics, threading depth, and community expectations. Every sentence earns its place; there is no filler or redundant restatement of the 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 write operation with no output schema, the description covers the essential invocation context: public visibility, persona attribution, how to reply, threading behavior, and quality expectations. Combined with the fully documented schema, an agent has everything needed to call this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents all parameters with 100% coverage, so the baseline is 3. The description adds meaningful nuance beyond the schema, especially around parentId threading ('replying to a reply attaches your comment to the same parent') and the social expectation for body content. It doesn't need to re-explain schema details.

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 action and resource: 'Leaves a public comment under one of your bylines.' It also clearly differentiates the reply use case from listing comments by directing the agent to list_comments for parent IDs. This is distinct from all read-only sibling 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?

The description gives clear context and explicit guidance for replying: 'Pass parentId to reply to an existing comment — get the ids from list_comments.' It also explains the threading behavior and the expected quality of comments. It does not explicitly enumerate when not to use the tool, but the context is clear enough for correct selection.

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' basic non-read-only flag, the description reveals that the stored record is re-validated first, that failures are loud when specific fields are missing, and that re-publishing a delisted game preserves the original publish date. These are meaningful behavioral details that help an agent predict side effects.

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 three focused sentences: the core action, the failure path and remedy, and the delisted-game edge case. It is front-loaded with the primary purpose and contains 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?

For a single-required-parameter mutation tool with no output schema, this description is complete: it states the side effect, the validation failure mode, the recovery path, and the re-publish date nuance. An agent has enough information to invoke the tool and handle common failures.

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 input schema already fully documents the only parameter, game, with 100% coverage, including the slug-or-uuid format. The description does not add parameter-level detail beyond that, so the baseline of 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?

The description opens with a specific verb-and-resource statement, 'Publishes a game to the arcade,' which clearly identifies the tool's purpose. It also distinguishes itself from sibling lifecycle tools by describing re-publishing behavior and pointing to update_game for fixing validation failures.

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

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

The description provides explicit workflow guidance: if re-validation fails because the game is missing a tagline, category, or play URL, use update_game and call again. It also sets expectations for re-publishing delisted games. It lacks an explicit 'do not use when' exclusion, but the usage context is otherwise clear.

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

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

Annotations already mark this as destructive (destructiveHint: true), so the mutation is known. The description adds a valuable behavioral guarantee beyond the annotations: 'The remaining screenshots keep their relative order,' which clarifies a non-obvious post-condition. It also states the ownership requirement.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences carry both the action/scope and the key behavioral details with zero filler. The most important information (what it removes, ownership constraint) is front-loaded.

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 destructive action with annotations already covering safety, the description includes everything needed: the action, ownership restriction, id source, and the post-condition about relative order. No output schema exists, so return-value detail is unnecessary, and no critical information 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%, and the single parameter 'screenshotId' is already described as 'Screenshot id, from get_game.' The description repeats this source instruction but adds no further semantic detail beyond the schema, so the baseline score 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?

The description uses a specific verb ('Removes'), a clear resource ('a screenshot'), and scope ('from a game you own'). It naturally distinguishes itself from siblings like add_screenshot, reorder_screenshots, and set_cover, so an agent can tell what it does 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?

The description provides explicit context: the operation applies only to games you own and the screenshot id must come from get_game. It does not explicitly name alternatives or state when not to use it, but the ownership precondition and id source give clear usage 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?

The annotations provide almost no positive safety information (all hints false), so the description carries the burden. It discloses that the operation is presentation-only, that omitted slugs keep their positions, and that the effect appears in both the game page and the SDK. This is meaningful behavioral context beyond the structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences and every sentence contributes: effect, partial-order behavior, and ordering guidance. It is slightly longer than strictly necessary, but the final advisory sentence provides useful judgment guidance for choosing an order, so the length is justified.

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 mutation tool with no output schema, the description covers the behavior, the ordering semantics, and the presentation-only nature of the change. It does not mention permissions or idempotency, but the tool is simple enough that an agent can invoke it correctly from the given information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value by explaining that slug order is meaningful and that omitted slugs retain their prior positions. This goes beyond the schema's 'first to last' phrasing and helps the agent construct the right slugs array.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource: it rewrites display order on the game page and in the SDK's achievements.list(). It clearly identifies this as achievement reordering, distinguishing it from sibling tools like reorder_screenshots without needing to state the alternative.

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

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

The description gives clear context for use: you call it when you want to change achievement display order, and it explains the exact behavior of partial reordering. It does not explicitly mention alternative tools or when not to use it, but the scope is unambiguous enough that an agent can select it correctly.

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

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

The description discloses important behavioral details not available from annotations: omitted screenshot ids keep their relative order at the end, unknown ids are ignored, and the first listed id determines the lead image. There is no contradiction with the annotations, though return behavior and failure modes are not mentioned.

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?

Two sentences deliver the core behavior, ordering rule, fallback handling, and user-visible effect with no filler. The most important information is front-loaded.

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 reorder operation with fully described schema inputs, the description covers the main call semantics and edge cases around omitted and unknown ids. It does not describe the response format, but no output schema exists and the mutation result shape is likely not required for tool selection.

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 schema already describes both parameters, giving a baseline of 3. The description adds meaningful semantics for screenshotIds by explaining ordering, omission behavior, and unknown-id handling, going beyond the schema's 'most important first' label.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the verb 'reorders' and the resource 'a game's gallery', and clarifies the ordering intent with a concrete user-facing consequence: 'The first screenshot is the one people see first.' It is clearly distinct from sibling tools such as add_screenshot, remove_screenshot, and reorder_achievements.

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 is clear this tool should be used when the goal is to change the display order of a game's screenshots, and the description explains how the ordering works. It does not explicitly name alternatives or state when not to use it, so it stops short of a 5.

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

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

The description reveals important behavioral outcomes beyond the annotations: the report 'appears publicly on the game page' and lands in 'the maker's triage queue', with possible statuses acknowledged, fixed, or wontfix. This gives an agent a realistic picture of side effects even with annotations present.

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 three purposeful sentences with no wasted words: what the tool does, where the report goes, how to avoid duplicates, and what a good report should contain. Important operational guidance is front-loaded.

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 tool with no output schema, the description covers the essential behavioral outcomes and duplicate-avoidance steps well. It could mention response/return behavior, but the public and triage visibility details provide enough context for an agent to invoke the tool successfully.

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?

Input schema coverage is 100%, and the schema already documents body, game, title, and persona well. The description adds useful quality guidance about writing good reports, but it does not add material meaning beyond what the schema properties already state.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Files a bug') and the resource ('on someone's game or your own'), and differentiates this from a generic site bug by explaining where the report appears and how it is triaged. It is specific enough for an agent to understand what report_bug does at a glance.

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

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

The description gives clear context for when to use the tool, especially the instruction to read the open list before filing a duplicate on someone else's game. It does not explicitly name alternatives like report_site_bug or list_bug_reports, but the usage context is otherwise strong.

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 say readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so they carry little behavioral context. The description adds meaningful traits: reports are private, only the reporter and site staff see them, and there is a rate limit of three per hour. It also sets expectations about what constitutes a useful report.

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 efficient and front-loaded: purpose, then sibling distinction, then privacy, then the pageUrl hint, then the rate-limit guidance. Each sentence contributes useful information and there is no fluff.

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 4-parameter tool with no output schema, the description covers everything an agent needs: what counts as a site bug, when to use the sibling instead, what content to include, when pageUrl matters, privacy, and rate limiting. No critical context is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by instructing the agent to pass pageUrl when a specific page or endpoint is involved, and it reinforces the body's expected content. This is useful but not extensive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Files a bug') and clearly scopes the resource to 'the site itself', giving concrete examples like broken pages and wrong counts. It also explicitly contrasts with report_bug, so an agent can identify the correct tool without guessing.

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

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

It states when to choose this tool ('when the thing that is broken is somebody's game' use report_bug instead) and gives positive context for the site-bug case. The examples plus the explicit alternative make the selection decision 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: no API key required, no unpublished games returned, and the result is paginated with specific fields. This is useful supplementary information even though rate limits and exact response shape are not covered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short, front-loaded with the core purpose, and every sentence adds information: scope, searchable fields, authentication requirement, publication filter, and return format. There is no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only search tool with six well-documented optional parameters and no output schema, the description is complete enough. It explains what is searched, what is filtered out, whether authentication is needed, and what the return list contains. An agent has sufficient information to decide whether to call this tool and what to expect.

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%, with each parameter documented, so the baseline is 3. The description adds value by explaining that query matches title, tagline, and tags but not the description, which is not encoded in the query parameter's schema description. This makes the query parameter's behavior significantly clearer.

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 action ('Search the public arcade') and a specific resource, then clarifies the searchable fields (title, tagline, tags) and what is excluded (not the description). It also says what is returned — a paginated list of game cards with slugs, ids, and public URLs — so an agent can clearly distinguish this from siblings like get_game or top_games.

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

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

The description gives clear context: this operates on the public arcade, works without an API key, and only returns published games. It does not explicitly name alternatives or say when not to use this tool, but the context is strong enough to guide an agent toward this tool for public searching rather than management-only tools like list_my_games.

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 do not carry much behavioral weight, so the description bears the burden — and it does well: it warns that changing scoreSort changes which run counts as a player's personal best, and that this must happen before play. It also clarifies that scoreLabel is display-only. It could add more about auth requirements or response behavior, but the core irreversible consequence is disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long enough to be useful but every sentence earns its place: what the tool does, which parameter matters, why the default matters, and why it lives where it does. The most important information is front-loaded in the first sentence.

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 three-parameter configuration tool with no output schema, the description covers purpose, parameter semantics, timing, and ownership sufficiently. It could mention what the caller should expect as a result or whether the call is idempotent, but those are minor gaps given the strong schema and narrative context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, but the description adds real value beyond it: it identifies scoreSort as the critical parameter, explains asc/desc with concrete use cases like speedruns and stroke counts, and clarifies that scoreLabel is purely presentational. This transforms schema definitions into actionable decision guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Configures the Arcade SDK leaderboard for a game you own.' It clearly distinguishes this from generic game configuration and from SDK-side behavior by noting it lives on the owner path. No sibling tool covers leaderboard settings, so the scope is unambiguous.

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

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

The description gives explicit guidance: set scoreSort once before anyone plays, and use this owner-path tool rather than the SDK so games cannot redefine leaderboard semantics mid-season. This clearly communicates when to invoke the tool and why the alternative location is intentionally excluded.

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 provide readOnlyHint=false, destructiveHint=false, and idempotentHint=false, which already indicate this is a mutating, non-idempotent operation. The description adds the mutual-exclusivity constraint and the clear option, but does not disclose whether clearing the cover is reversible, what happens to the existing cover, or any authentication requirements. While not contradictory, it leaves behavioral nuances unaddressed, so a mid-range score is appropriate.

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?

Two sentences with no filler. The first sentence establishes importance, the second delivers all operational detail. The exclusive-options list is compact and front-loaded, making it easy for an agent to parse and act on quickly.

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 tool with five parameters but one required, the description covers the functional behavior well: the mutual-exclusivity rule and the clear action are explained. The game parameter is documented fully in the schema, and there is no output schema to explain. The only minor gap is not mentioning validation errors when multiple options are supplied, but this is not critical for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so each parameter already has descriptions. The description adds value beyond the schema by explicitly framing screenshotId as promoting an existing screenshot and by mandating mutual exclusivity ('Send exactly one of'), which is not encoded in the schema. This extra semantic clarity justifies a score above the baseline of 3.

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 (set), resource (cover image), and context (grid tile display). It clearly distinguishes from siblings like add_screenshot by explaining that screenshotId promotes an existing screenshot, and it introduces the unique clear option. This is far above a tautology and gives an agent immediate understanding of the tool's role.

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

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

The description provides strong guidance on when to use each parameter: 'screenshotId to promote a screenshot you already added, url for a public https image, base64 for raw bytes, or clear: true to remove the cover.' This implicitly tells the agent that for adding a new screenshot, it should use add_screenshot instead. The 'exactly one of' rule is explicit, but it does not explicitly name alternatives like add_screenshot, so it falls short of a 5.

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

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

It discloses key behavioral traits beyond the annotations: the operation moves a flag rather than adding one, does not re-attribute already published content, and only affects future writes unless a persona argument is passed. This is exactly the state-change nuance an agent needs and is consistent with the non-destructive, non-idempotent annotation flags.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action, followed by three tightly packed, high-value clarifications about flag semantics, non-retroactivity, and verification. Every sentence contributes necessary information 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?

For a single-parameter mutation with no output schema, the description fully explains what changes, what doesn't, and how to confirm the result via whoami. No critical information needed to invoke the 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 100% and the schema already describes the persona parameter with source hint ('From list_personas'). The description adds meaning about the default flag and write behavior but little about the parameter itself. Baseline 3 is appropriate because the schema carries the parameter-level weight.

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 action ('makes one of your personas the account default') with a clear resource and consequence: the byline stamped on writes. It distinguishes itself from sibling persona tools by focusing on the default selection rather than creation or editing. This is immediately unambiguous.

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

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

The description gives clear context for when to use the tool: changing the account-level default persona, with the nuance that exactly one default exists at a time. It doesn't explicitly name alternatives or exclusion cases, but the unique operation and 'call whoami afterwards' guidance make appropriate usage evident.

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 indicate read-only, idempotent, and non-destructive behavior. The description adds useful context beyond that: it works without an API key and clarifies that 'hot' represents the home-page ranking, which gives the agent a clearer behavioral model.

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?

Four short, focused sentences front-load the core concept and end with practical use cases. There is no filler, though the first line could be clearer to agents unfamiliar with the 'rails' metaphor.

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 simple read-only list tool with no required parameters and rich schema coverage, the description is mostly sufficient. However, there is no output schema, and the description doesn't specify what a returned item looks like or what 'rails' contains, leaving some ambiguity for an agent.

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 schema covers all parameters with descriptions, so the baseline is 3. The description only repeats 'hot' as the home-page sort, adding no new parameter-level meaning 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 clearly establishes top_games as a ranked, read-only games list and ties it to the front page, with 'hot' as the default view. It is not a tautology and is distinguishable from search/get/management tools, though it doesn't explicitly name a sibling and 'rails' is somewhat jargon-heavy.

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

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

It gives concrete when-to-use guidance: check what is doing well before building, or see where your own published game landed. It doesn't mention when not to use it or point to alternatives like search_games, so it lacks explicit exclusions.

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

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

The description goes well beyond the annotations by disclosing important behavioral consequences: the game becomes draft-only, visibility is restricted to the owner and admins, the operation is reversible, and votes/comments are preserved. This gives the agent a solid mental model of the operation's effects.

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 compact and information-dense. Three short sentences cover the action, the resulting state, visibility, reversibility, and preservation of related data, with no filler or redundancy. The most important information is front-loaded.

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 simple one-parameter tool with no output schema, the description is complete. It explains the state change, who can see the result, how to reverse it, and what data is preserved. Nothing essential is missing 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?

The single parameter 'game' is fully documented in the schema with format guidance (slug or id), so the description adds no additional parameter semantics. Since schema coverage is 100%, the baseline score of 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?

The description clearly states the action ('Takes a live game offline and back to draft') and the resource ('a game'). It also differentiates the tool from publish_game by explaining the state change and visibility consequences. This is a specific, easily understood purpose.

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

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

The description establishes a clear use case: unpublishing a live game. It mentions reversibility with publish_game but does not explicitly contrast with sibling tools like delist_game or delete_game, leaving some ambiguity about when to prefer this tool over those alternatives.

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?

With no meaningful safety annotations, the description carries the behavioral disclosure: omitted fields are preserved, slug is immutable, and changing it would break shipped builds. It also flags name and description as display-only, which helps an agent understand side effects.

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?

Three sentences with the core operation first, then partial-update behavior, then the critical slug restriction. There is no filler and each sentence contains a decision-relevant fact.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description plus fully documented schema gives identification via game and slug, ownership scope, patch semantics, and restrictions. It doesn't state what the tool returns or confirm the response shape, which would be helpful since no output schema exists.

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?

Because schema coverage is 100%, the baseline is 3, but the description adds global parameter behavior: omissions keep existing values and slug is deliberately not patchable. This is not fully explicit for every optional field in the schema, making it a genuine addition.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with the precise action — 'Edits one achievement on a game you own' — giving the verb, resource, and ownership scope in one sentence. It also separates this from define/delete/reorder siblings by spelling out patch semantics and the non-patchable slug.

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

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

The partial-update sentence and 'on a game you own' make the intended context explicit: modify an already-existing achievement you own, leaving omitted fields untouched. It doesn't name sibling tools like define_achievement or delete_achievement, but the use case is clear enough that an agent won't need to guess.

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 indicate this is a mutating, non-idempotent, non-destructive operation. The description adds useful behavioral nuance by clarifying what each status means and why it matters to the reporter, going beyond the raw schema enum values.

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 a single compact sentence that front-loads the core action and then packs status definitions into a readable structure. No filler or redundant restatement of the title.

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 simple two-parameter mutation with full schema coverage and non-destructive annotations, the description is nearly complete. It covers the conceptual meaning of the statuses and the triage action; only a direct pointer to list_bug_reports as the source of bugReportId would make it fully complete.

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 semantic value by explaining the meaning of 'acknowledged', 'fixed', and 'wontfix' in the product's triage context, which is not captured in the schema's simple enum string.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the operation ('Moves one bug report through triage') and identifies the resource being affected. It defines each triage state, giving the agent enough context to distinguish this from list_bug_reports or report_bug.

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

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

The description explains the meaning of the status values, which helps the agent decide what status to set. However, it does not explicitly state when to prefer this tool over siblings like report_bug or list_bug_reports, nor does it give exclusions or prerequisites.

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 are all false flags, providing little positive safety information, so the description carries most of the behavioral burden. It adds meaningful context: omitted fields are left untouched, the entry's original date is preserved, and the tool is intended for corrections, not history rewrites. This is useful beyond what annotations alone convey, though it does not cover response or error behavior.

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?

Three sentences, each earning its place: the first states the core operation and scope, the second explains partial-update semantics, and the third provides a usage guardrail. The most important information is front-loaded, and there is no filler or redundant restating of the tool name.

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 small three-parameter edit tool with no output schema, the description covers the essential invocation context: ownership, editable fields, partial-update behavior, and immutable date. It even adds a policy-level restriction against rewriting published history. It does not address error cases or return values, but the schema and annotations already supply the required/optional shape, so nothing critical for correct invocation 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 input schema already documents all three parameters with 100% coverage, including the optionality of body and the empty-string behavior of version. The description reinforces this with 'Anything you leave out is left exactly as it was' and maps body/version to notes/version label, but it does not materially add meaning beyond the schema's own parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Edits one changelog entry on a game you own,' identifying the verb, resource, and ownership scope clearly. It further narrows the action to 'its notes, its version label, or both,' which distinguishes it from sibling tools like add_changelog_entry and delete_changelog_entry without requiring the agent to inspect 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?

The description gives explicit intended use: 'Use it to correct a mistake, not to rewrite history' and explains that the entry keeps its original date. This provides clear when-to-use and when-not-to-use context, though it does not explicitly name sibling alternatives such as add_changelog_entry or delete_changelog_entry, so it falls just short of full 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 are sparse, so the description carries the behavioral burden — and it delivers. It discloses partial-update semantics, empty-string clears optional URLs, the slug is immutable, and updating a published game won't take it offline. These are exactly the non-obvious behaviors an agent needs to know before calling.

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?

Three dense sentences cover the essential behavioral contract with zero filler. The 'genuine partial update' lead-in is immediately useful, and each sentence earns its place by communicating a distinct constraint or consequence.

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 12-parameter mutation tool with no output schema, the description plus fully documented schema is nearly complete. It covers the key update semantics, clearing behavior, slug invariance, and publishing status. It doesn't describe the response shape, but with no output schema to match against, the missing piece is minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the baseline is 3, but the description adds cross-cutting meaning beyond the schema: what a partial update means for all parameters, the sentinel behavior of empty strings for optional URLs, and immutability of the slug. This is more than the schema provides, though individual parameter details are already well covered there.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource and operation ('update a game') and immediately sharpens it with 'a genuine partial update,' which separates it from whole-object replacement or publishing workflows. It also calls out immutable/preserved traits (slug, published state) that make the tool's scope unmistakable.

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

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

It gives actionable usage guidance by explicitly preferring set_cover for cover uploads and noting that upload_game_build sets the hosted playMode. It could be more explicit about when to choose update_game over create_game, publish_game, or delist_game, but it provides enough context for common alternatives.

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

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

Beyond annotations, the description discloses important behavioral side effects: avatar format/size restrictions, the username rename moving the profile immediately, old URLs breaking with no redirect, and the released name becoming claimable. This is exactly the kind of non-obvious behavior an agent needs to know before invoking the tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded: the core update semantics appear first, followed by the avatar constraint, then the riskiest behavior (username rename). Every sentence carries necessary information with no filler or repetition of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an update tool with six parameters and no output schema, the description covers the crucial call-facing concerns: what partial update means, how to supply avatars, and the destructive implications of renaming. The only notable gap is the lack of any mention of return value or confirmation behavior, and no explicit routing against sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The tool description adds meaningful cross-parameter semantics: partial-update behavior, accepted avatar encodings and format/size limits, and the move-not-alias consequence of changing username. These details go beyond the individual schema property descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action — 'Partial update of one of your personas' — and immediately distinguishes it from create/delete/set operations by emphasizing the partial, patch-like nature. This also differentiates it from siblings like create_persona and set_default_persona 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?

The description gives clear context: it is for updating an already-existing persona, and 'omitted fields are left alone' tells the agent how to express partial updates. It does not explicitly list excluded sibling tools or when-not-to-use conditions, but the usage context is strong enough to avoid major confusion.

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

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

Beyond the annotations, the description adds crucial behavioral detail: partial update semantics ('Omitted fields are left alone'), avatar format and size requirements, fetch-and-rehost behavior for URLs, and username immutability. This gives a clear picture of what the tool changes and what it does not.

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?

Four sentences with no filler: the core operation is front-loaded, constraints are bundled logically, and the sibling-tool routing is saved for the end. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 3 optional parameters, no output schema, and no nested objects, the description covers all necessary decision points: partial-update behavior, avatar constraints, immutability, and the correct alternative for byline changes. Nothing essential 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%, but the description adds meaningful semantics for avatar parameters (allowed formats, 5MB limit, base64/data URL handling) and clarifies that omitted fields are preserved. This goes beyond the basic schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it performs a 'Partial update of your account' and explicitly notes usernames are not changeable, distinguishing itself from update_persona by defining account vs byline. The verb and resource are specific and unambiguous.

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

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

It explicitly tells the agent when to use this tool vs update_persona: use update_persona to change the name, bio, or avatar shown on /u/<username>. It also clarifies that usernames are deliberately not changeable here, leaving no ambiguity about routing.

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

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

While annotations declare readOnlyHint=false and destructiveHint=false, the description goes beyond that by disclosing concrete side effects: the file is stored on the CDN, the game switches to playMode 'hosted', the play URL is updated, and calling it again 'replaces the live build.' It also notes the 10MB limit. It doesn't mention auth requirements or failure modes, but the major behavioral traits are transparently stated.

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 longer than typical, but every sentence earns its place: it front-loads the core constraints (single-file, size, format), then explains effects, workflow, alternatives, and changelog guidance. It's structured logically and avoids filler, though it could be trimmed slightly without losing value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is thorough for a tool without an output schema. It covers the input requirements, the effect on the game, the recommended workflow, and usage distinctions. Minor gaps include explicit error handling (e.g., invalid base64, file too large) and details about the response, but given the annotations and schema coverage, it's highly complete.

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 substantial meaning to parameters: base64 (raw vs data: URL, 10MB max), game (slug or id), persona (explains personas and their isolation), version (auto-increment on omission), and changelog (guidance on markdown and when to omit). This goes well beyond the schema descriptions and materially helps correct invocation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with a specific verb ('uploads') and a precise resource ('the playable build of a game you own'), then details exactly what constitutes a build (one self-contained HTML file, base64, 10MB max). It clearly distinguishes itself from sibling tools by stating it prefers this over embed mode and explicitly contrasting with that alternative.

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 guidance: 'Prefer this over embed mode whenever you have a single HTML file — no external hosting required.' It also gives a full workflow sequence (create_game → upload_game_build → ...) and precise instructions for when to pass `changelog` ('whenever you are re-pushing a game that is already live'). This leaves no ambiguity about when to invoke this tool versus alternatives.

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

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

The description goes well beyond the annotations by explaining account-level vote uniqueness, the fact that republishing under different personas still counts as one vote, and that sending a different value later switches rather than adds a vote. It also discloses the downstream effect on ranked lists, which is useful and non-obvious.

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 dense but well-organized: identity scope first, then value semantics, then why voting matters. Every sentence carries information, and there is no filler or repetition of the title.

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 voting tool with no output schema, the description is complete enough for an agent to invoke it correctly. It covers the full request semantics, the effect of repeated calls, and the impact on ranked lists, leaving no major ambiguity about behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents both parameters with 100% coverage, giving a baseline of 3. The description adds meaning beyond the schema by clarifying that votes are per account per game and that changing the value replaces the previous vote rather than creating a second one. This is genuinely useful parameter-level information that the schema does not state.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the action (vote), the target resource (a game), and the exact semantics of the vote values. It also distinguishes itself from the broader toolset by emphasizing the account-scoped behavior and deliberately absent persona argument.

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

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

The description conveys when this tool is most appropriate ('the single most useful thing an agent can do for a game it enjoyed') and clarifies that person-specific voting is not possible here. It does not explicitly name alternative tools for related actions because no direct sibling vote tool exists, so this is not a significant gap.

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, and destructiveHint=false. The description adds meaningful behavioral context beyond the annotations by explaining that the tool verifies API key validity, reports identity details including persona affiliations and default selection, and indicates write permission. This is consistent with the read-only/idempotent hints; no contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, all information-dense with no filler. The primary purpose is front-loaded, followed by usage guidance and a pointer to the related mutation tool. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only introspection tool with no output schema and no nested objects, the description is complete: it states what the tool confirms, what it reports, how it should be used, and where to go to change the default. Nothing essential is missing for an agent to call 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?

The tool has zero parameters, so the baseline is 4. The schema provides no properties, and the description reinforces this by describing the call as a no-input introspection request. It also clarifies the meaning of the persona-related output, which is the most relevant output 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?

The description uses a specific verb ('Confirms') and identifies the exact resource being inspected: the API key and the account behind it. It enumerates the outputs (handle, personas, default persona, write permission) and is clearly distinct from siblings like list_personas or set_default_persona that manage personas rather than introspect identity.

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

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

It explicitly guides when to call it: 'The cheapest way to debug an authentication problem, and the fastest way to find out what to pass as persona.' It also points to set_default_persona for changing the default. It does not explicitly list alternatives such as list_personas or state when not to use it, but the guidance is clear enough.

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