klyo games: publish HTML5 browser games

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

Annotations only indicate non-read-only and non-destructive, leaving the tool's write nature implied. The description adds valuable behavioral details: the post appears immediately with no moderation queue, and linking to a game adds a play button. This goes beyond the annotations and helps the agent anticipate the outcome.

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, with a clear main purpose stated first, followed by a key behavioral note and three illustrative examples. It avoids redundancy and is well-organized for quick scanning, though it could be slightly more streamlined.

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 6-parameter tool, the description covers the core purpose, the immediate visibility, the linking effect, and typical use cases. It does not detail error handling or return values, but the absence of an output schema and the simplicity of the operation make this acceptable. Overall, an agent can confidently invoke the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic value beyond the schema by explaining the effect of gra_slug (readers get a play button) and by contextualizing the post types with examples. This extra guidance justifies a 4.

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 writes a post in the klyo games community and enumerates the specific post types (question, playtesters, launch, showcase). This is a distinct resource and verb, and it is unambiguous compared to sibling tools that all handle game management rather than community posting.

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 concrete examples of when to use the tool (launch, playtesting, showcase) and explains the immediate visibility and linking behavior. It does not explicitly name alternative tools or exclusions, but since no sibling tool serves the same purpose, the usage context is sufficiently 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 annotations, it discloses the immediate public replacement of the previous text, the read-only fallback, the consent requirement, and the 'do not invent facts' constraint. This is consistent with destructiveHint=true and adds meaningful behavioral context.

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 and front-loaded: purpose, then mode behavior, then safety constraint, then examples. Every sentence adds operational or policy value; there is little wasted text.

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

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

For a 2-parameter tool with no output schema, the description is complete: it explains what is returned in read mode, what happens on save, what the only allowed source material is, and what constraints apply. An agent has enough 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%, so the baseline is 3, but the description adds important semantics: omitting both parameters means read-only, omitting one preserves its current value, and saving goes through the same check as the studio. These are not evident 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 identifies a specific resource ('the developer's profile card on games.klyo.pl') and the concrete actions: read or write the 'about me' text and tagline. The 'YOU WRITE' context and profile-card scope clearly separate it from the game-management 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 explicit conditions: without `o_mnie` and `haslo` it reads; with them it saves, and an omitted field stays unchanged. It also adds a strong usage rule: show the owner the text first and save only with consent. It doesn't explicitly name alternatives, but no sibling tool covers the profile card.

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 destructiveHint:true and readOnlyHint:false, but the description adds substantial behavioral detail: the first call removes from catalogue and takes the page down while keeping the address, a second call removes it for good, and scores/reviews remain tied to the address. It also explains the non-game package path via `upload_id`, which is beyond what annotations convey.

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

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

The description is a well-structured paragraph with examples, front-loaded with the primary action. It is somewhat verbose but every sentence contributes meaning—covering the two-step process, data persistence, and parameter selection. The examples at the end aid comprehension without redundancy.

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

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

For a destructive tool with no output schema, the description covers the key behavioral aspects: what happens on first and second calls, what data persists, and how to handle packages. A minor gap is that it does not explicitly state that `slug` and `upload_id` are mutually exclusive or that at least one is required, though the description strongly implies it. Overall, it provides sufficient guidance for an agent to call 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% (both parameters have descriptions), but the tool description goes further by explaining the provenance of each parameter (e.g., `slug` from klyo_my_games, `upload_id` from klyo_upload_package) and the conditions under which each is used. This adds contextual value beyond the schema's own descriptions.

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

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

The description states a specific action: 'Take this account's game (`slug`) off the portal.' It clearly distinguishes this from siblings like klyo_update_game or klyo_publish_game by focusing on removal. The two-step deletion process is explained, making the tool's purpose 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 usage context: 'Use it to clean up after a failed attempt, for example when two entries of the same game ended up in the waiting room.' It also clarifies when to use `slug` vs `upload_id` and notes that a second call on an already-down game permanently removes it. Examples illustrate common scenarios, leaving no ambiguity about when to invoke this 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 are minimal (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description carries the full behavioral burden—and it succeeds. It discloses that the owner watches and submits themselves, klyo runs no model and saves nothing, invalid fields return in `odrzucone` with reasons, and certain sections (questionnaire, statements, consents) are intentionally not filled. This is far beyond what annotations provide.

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

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

The description is long but each paragraph adds necessary operational detail: live nature, with/without `pola` behavior, exclusions, and examples. It front-loads the core purpose and then structures the details. It is dense but not wasteful; the examples are practical. A slightly shorter version could exist, but the complexity justifies the 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?

The description covers usage, limitations, validation, privacy, and return indicators (`odrzucone`, `formularz_otwarty`). It does not fully specify the output structure, but since there is no output schema, the description gives enough for an agent to understand the response flow. The nested parameters are exhaustively documented in the schema, so the description complements rather than duplicates.

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 provides 100% description coverage for the `pola` parameter and all nested fields. The tool description adds meaningful behavior beyond the schema: omitting `pola` returns the field list, allowed genres/moods, rules, and `formularz_otwarty`; providing it sends values live and invalid ones come back in `odrzucone`. This clarifies the interactive contract and response handling.

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

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

The description uses a specific verb and resource: 'Types fields into the OPEN “New game” form in the developer's studio (dev.klyo.pl)'. It clearly distinguishes itself from siblings by emphasizing the live, owner-watched nature and explicitly excludes filling content questionnaire, statements, or consents. An agent can easily tell this apart from update_game or delete_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 provides explicit examples of when to use the tool ('Fill in the new game form on klyo') and negative guidance ('You do NOT fill in the content questionnaire...'). It explains the conditional behavior with and without `pola`, and states corrections are sent with the same tool. However, it does not explicitly name sibling alternatives like klyo_update_game for existing games, leaving that distinction somewhat implicit.

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

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

Annotations declare destructiveHint=true, and the description's mutation semantics align with that (no contradiction). The description adds substantial behavior beyond annotations: patch semantics ('everything else stays as it is'), the language policy (required <en> of at least 25 words, +40 XP for <pl>, translations going through klyo_game_translate as owner-approved proposals, klyo not translating on its own account), and the refusal behaviors (nazwa_z_haslem, brak_hasla, opis_en_wymagany). This is rich, non-redundant behavioral context.

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

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

The description is long but every section earns its place: the core purpose and sibling distinction are front-loaded, the language rules are critical for a multilingual catalog, and the examples at the end are genuinely illustrative. It is well-paragraphed with clear topic breaks. Slightly dense, but not padded.

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

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

For a 26-parameter tool with nested objects and no output schema, the description covers the most important cross-cutting behaviors: patch semantics, the content-vs-package split, the translation pipeline, and the language-tag requirements. The schema handles per-parameter detail. The only minor gap is that the description doesn't describe return values, but for a patch-style update tool this is acceptable given the schema richness.

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

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

Schema description coverage is 100%, so the schema already documents all 26 parameters in detail. The description does add one cross-parameter behavior — the 'pass ONLY the fields you change' replace semantics — but it does not add per-parameter meaning beyond the schema. Baseline 3 is appropriate when the schema carries the burden.

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 ('Change the CONTENT of a game that is already in the catalogue') and enumerates the affected fields (name, tagline, description, controls, round length, genre, shelves, mood, languages, layout, score limit, stage, store links, questionnaire, age). It explicitly names the sibling it is not (klyo_update_game for the package), so an agent can select it correctly 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 distinguishes this tool from klyo_update_game ('It does NOT touch the package: replacing files is klyo_update_game'), explains WHY they are separate ('A typo in the description should not cost that'), and adds the critical patch semantics ('Pass ONLY the fields you change'). It also gives three concrete usage examples that show when the 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?

Beyond the annotations' readOnlyHint=false, the description discloses key behavior: frames are captured by the system once the game is live, the first call lists rather than mutates, and setting a mismatched cover can lead to the game being taken down. It also makes the no-custom-image policy explicit, which is a constraint an agent could not infer 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?

The description is longer than minimal, but every sentence contributes a distinct fact: purpose, release timing, selection workflow, and content policy. It is front-loaded with the action and uses examples compactly; it could be tightened slightly, but nothing is filler.

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

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

For a two-parameter tool with no output schema, this definition covers the full call sequence, prerequisites, the source of frames, and the policy that governs acceptable covers. The examples also show natural user phrasings, leaving little ambiguity about how to invoke the tool.

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

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

The schema already covers both parameters at 100%, so the baseline is 3. The description adds value by explaining that omitting 'klatka' returns a list of frame addresses and that the number selects one of those frames, with an example showing 'the second frame' as the argument.

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 ('Set') and resource ('the tile players recognise the game by in the catalogue'), so the role of the tool is immediately clear. It also distinguishes klyo_game_cover from generic update tools by explaining its unique mechanism: covers must be screenshots from the running game, never custom images.

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 an explicit two-phase workflow: call without 'klatka' to list available frames, then call again with the chosen frame number. It also states the temporal precondition (frames exist only after klyo_publish_game) and the hard exclusion (no custom images), giving the agent clear when-to and when-not-to 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?

Although annotations already declare read-only safety (readOnlyHint, idempotentHint, destructiveHint false), the description adds substantial behavioral context beyond them: measurement queue limits (6 per hour, one at a time, full counts as two), browser-as-sensor requirement, thumbnail overwriting behavior, and detailed verdict interpretation. This is unusually rich disclosure of side effects and constraints.

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, very long paragraph that mixes purpose, return field definitions, workflow instructions, verdict codes, and motivational asides like 'YOUR BROWSER IS THE EYE HERE.' While it front-loads the 'Read `_najpierw` first' point, many sentences do not earn their place for tool selection or invocation, making it hard to scan.

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 must explain return values, and it does so extensively: the `_najpierw` object, error fields, verdict codes, and measurement outputs. Combined with 100% schema coverage and annotations, it provides complete context for an agent to call and interpret the tool. Minor gaps like the exact response envelope are not critical.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including `sesja`, `zmierz`, `pelny`, `slug`, `upload_id`, and `jezyki`. The description largely repeats or contextualizes these without adding new syntax, defaults, or constraints beyond what the schema provides. A baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The title 'Why the game is not working' and the opening 'Read `_najpierw` first' make the diagnostic purpose clear, with a specific verb (read/diagnose) and resource (game release blocker and error data). However, the description immediately dives into return field names instead of stating a crisp purpose, and it never names sibling alternatives like klyo_fix_game or klyo_game_files to differentiate.

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 precise workflow: open the preview on your side, play it, then ask this tool; it also provides a no-browser alternative (`zmierz: true`) and a production profile (`pelny: true`). It states the consequence of reversing the order and warns against reporting certain verdicts as ready. It stops short of explicitly comparing to sibling tools, but the when-to-use 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as safe, so the description adds value by explaining exactly what is read (text files, not images/sounds), size limits (200 KB), pagination (from_line, lines), and how it selects the version (waiting vs. players). This goes beyond the annotations without contradiction.

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

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

The description is well-structured: it starts with the core purpose, explains the different modes, then provides concrete examples. Every sentence adds value, and the examples are practical for an agent to understand the tool's usage patterns.

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 tool with comprehensive schema descriptions, the description covers all essential behavioral details: file list format, content reading constraints, changes comparison, version selection, and hash usage. No output schema exists, but the tool's return values are implicitly described, making it complete for agent 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 schema covers all parameters with descriptions (100% coverage), so the description doesn't need to repeat them. However, it adds context about how parameters interact (e.g., path vs. no path, changes with list, hash usage) and clarifies optionality, which slightly exceeds the schema's baseline.

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

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

The description clearly states the tool reads a game's files, with a specific verb and resource, and distinguishes between reading the file list vs. file content vs. changes. It also differentiates from siblings by focusing on reading rather than patching or uploading.

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 explains when to use the tool (to read files from a game or waiting-room package), how to use it (with slug or upload_id, with or without path), and provides examples for common use cases. It does not explicitly mention alternatives, but its unique purpose is clear given the sibling list.

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 the tool is destructive and not read-only. The description goes far beyond this: it explains the workshop copy, that players keep the old version until release, all-or-nothing application, conflict behavior with `expected_hash`, the klyo check, checkpoint/revert/discard semantics, expiry, and limits. This is rich, useful behavioral disclosure.

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

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

The description is long but dense and well-organized, with labeled sections (UNDO, Limits) and examples at the end. It front-loads the core editing behavior before alternates and edge cases. Some repetition with the schema exists, but most content 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 complex 7-parameter tool with no output schema, this description is nearly complete: it covers target selection, edit modes, uploads, atomicity, conflict handling, undo, release flow, and limits. It names the key response artifacts (`upload_id`, `auto-N` checkpoint) but does not fully describe the response shape, which is the main gap.

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

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

The input schema already covers 100% of parameters with detailed descriptions, so the baseline is 3. The description adds extra semantic value by explaining relationships: `slug` vs `upload_id`, `expected_hash` conflict prevention, `from_upload` as a no-base64 alternative, and `nowa` applying edits in the same call. It doesn't enumerate every parameter, but the schema handles that.

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: 'Edits a game's text files... without a ZIP' and defines the targets (`slug` or `upload_id`). It also differentiates this from release, publish, and upload tools by explaining the workshop workflow. The examples reinforce the intended actions clearly.

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 routes usage: game `slug`, waiting-room `upload_id`, or `nowa` for a game from scratch. It names the follow-up tools (klyo_release_version, klyo_publish_game) and the upload mechanism (klyo_upload_package), giving an agent clear when-to-use and when-to-hand-off 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?

With annotations already declaring readOnly=false/openWorld=false/idempotent=false, the description adds substantial context beyond them: execution happens on the owner's device, the owner must click 'Allow' in the studio, they can watch and stop it, input is synthetic (not trusted events), pointer lock is simulated, and `request_id` makes retries idempotent. It also enumerates the `stan` status codes (brak_urzadzenia, karta_w_tle, zatrzymane, etc.) and the evidence/dowod_urzadzenia outcome.

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 opening sentence front-loads the purpose and the target/session model follows logically. It is dense and long, with a status-code list and evidence paragraph that tax readability, but for a 9-parameter tool with a nested step timeline most sentences carry real information.

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

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

No output schema exists, so the description must carry the return-value burden — and it does: screenshots as image content, game state, `stan` codes, `dowod_urzadzenia` evidence, and how klyo_game_diagnostics surfaces it. Combined with the permission/Allow prerequisite and session lifecycle, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description meaningfully complements it by explaining the step grammar: steps run on one timeline of at most 3000 ms, each starts when the previous ends or at `at_ms` for parallelism, coordinates are fractions 0-1, up to 40 steps and 4 screenshots, and it lists the fields per step type. This composition semantics goes beyond the per-field schema text.

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

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

The description names a specific verb+resource ('Really play your game and see it: you send input steps, you get screenshots (image content) and the game state') and explicitly frames the mode as remote-on-owner's-device. It also distinguishes itself from siblings by tying its target to 'the same version klyo_game_files reads' and routing failures to klyo_game_diagnostics.

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 session lifecycle is spelled out clearly ('The first call opens the game, next calls continue it, `restart` reloads it, `close` ends the session'), and the error path names an alternative ('Errors from this session: klyo_game_diagnostics with `sesja` = `sesja.znacznik`'). It does not state explicit when-NOT-to-use conditions versus siblings like klyo_game_files, 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?

Annotations already mark this as read-only, idempotent, and non-destructive, and the description adds meaningful behavioral context: the standard is in Polish, includes a local test that mirrors the server's publish test, and covers specific areas like screens, input, social layer, and legal/brand concerns. No contradiction exists.

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-structured: it front-loads the critical call-first instruction, then summarizes the standard's contents, then gives usage examples and a completion gate. Each sentence earns its place without 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 no-parameter, read-only tool with no output schema, the description fully covers what the agent needs: when to call it, what it returns, what the returned standard contains, that it is in Polish, and how to know when the game is actually done.

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 and 100% schema coverage, so there is no parameter-level detail to add. The description reinforces this by saying 'Read-only, no parameters,' which is sufficient for a schema with an empty properties object.

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 returns the 'studio quality' game production standard and opens with 'CALL THIS FIRST'. It distinguishes itself from siblings by being the requirements/contract tool rather than a scaffold, form, or publish tool.

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

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

It explicitly instructs the agent to call this before designing or writing any game code, and gives a concrete example: when the user says 'make a battleship game', the agent should not ask about phones, leaderboards, or sound. It also sets the completion condition: do not say 'done' until `klyo-test` passes.

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, and the description repeats 'Read-only' (redundant). However, it adds substantial behavioral context beyond annotations: the kit includes sound that resumes after backgrounding, safe areas, input handling unified, and the constraint 'You write ONLY the gameplay'. These are useful behavioral traits not 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?

The description is long but front-loaded with the purpose and workflow, then efficiently lists features in a colon-separated list. It includes examples at the end. Every sentence contributes to informing the agent about what the tool returns and when to use it, 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?

Given the tool has one optional parameter and no output schema, the description covers the return (two files and the API), the usage sequence, the parameter options, and example queries. It does not specify the exact format of the returned API, but that is likely in the files. The description is sufficient for an agent to decide when and how to call it.

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

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

The schema has 100% coverage for the single parameter `rodzaj`, with detailed descriptions of each enum value. The description repeats these explanations and adds a reference game ('Reference game: Battleships'), but this is a minor addition. It does not compensate significantly beyond what the schema already provides.

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 ('returns') and resource (two starter files and the kit API) with a clear header 'GAME SKELETON ON KLYO KIT'. It distinguishes itself by explicitly placing it in the workflow: 'call after klyo_game_requirements, before you write code', which separates it from siblings like klyo_game_requirements and klyo_game_sdk.

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: 'call after klyo_game_requirements, before you write code' and includes three example prompts that would trigger this tool. It does not explicitly list alternatives or when-not-to-use, but the sequence and examples give clear context for an agent.

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. The description adds that it 'needs no input' and describes the content scope. It doesn't contradict annotations and provides useful context about what to expect (a full description), though it doesn't detail return format or pagination – minor for an info 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 longer than minimal, but every sentence earns its place: content enumeration, read-only note, usage ordering, consequences, and example queries. It is front-loaded with what the tool does and provides actionable guidance. Slight verbosity prevents a 5.

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

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

Given the tool has no parameters and no output schema, the description is fully sufficient for an agent to decide when and how to call it. It covers purpose, prerequisites, and example triggers.

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

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

With 0 parameters and 100% schema coverage, the baseline is 4. The description explicitly states 'needs no input,' reinforcing the schema. No further parameter explanation is needed.

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 this tool provides the full SDK kit description, enumerating specific capabilities (leaderboard, saves, full screen, ad break, rewarded ad, clip recording). It distinguishes itself from siblings by explicitly ordering it after klyo_game_requirements and before game development.

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

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

Gives explicit when-to-use guidance: 'CALL THIS RIGHT AFTER klyo_game_requirements, BEFORE YOU WRITE A GAME FOR klyo.' Also explains the negative consequences of skipping it (no leaderboard, no cross-device saves, ads will fail checks). This leaves no ambiguity about when to invoke this 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, so the description carries little safety burden. It adds the 'day by day' granularity and the revenue context, but it does not describe response format or behavior beyond what the schema's sprawdz_google parameter already explains.

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 core purpose is front-loaded in the first sentence, and the examples are compact and useful. There is no fluff or repetition of schema-level detail.

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, idempotent stats tool with fully described parameters and no output schema, this is nearly complete: it states the metrics, granularity, scope, and safety. It lacks only an explicit note on response shape or pagination, which is a minor gap.

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

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

Schema description coverage is 100%, so all parameters are fully documented in the schema. The description's examples illustrate slug use but add no 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 identifies what the tool returns: daily visits and plays for a specific game, with example queries showing intended use. It does not explicitly contrast this with siblings such as klyo_game_diagnostics, so some differentiation is left to inference.

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 examples like 'How many people played my game this week?' and the mention that ad revenue share is calculated from this data give clear usage context. It does not state explicit exclusions or alternatives, but the intended scenarios are easy to infer.

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?

Despite no annotations (readOnlyHint=false, etc.), the description fully discloses the non-destructive proposal nature, the check rules, failure handling, and that nothing is saved as final until owner approval. It also clarifies that klyo runs no model and the owner pays for translation.

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

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

The description is long but well structured with clear steps and rules. It is front-loaded with the purpose and key constraints. However, some repetition of check rules could be condensed, but overall it is organized and each part adds 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?

Given the complexity (two-step, multiple languages, validation rules), the description provides all necessary information: the workflow, the fields, the checks, the failure handling, and the approval process. No output schema exists, but the description explains what comes back (odrzucone, saved proposals).

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 the parameters well (100% coverage). The description adds context on the structure of tlumaczenia (all fields from oryginal) and the meaning of languages, but does not add new parameter-specific syntax details beyond 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 ('translate') and resource ('a game's texts'), and explains the two-step process. It clearly distinguishes from sibling klyo_fix_game by noting it does not change the developer's own texts.

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 defines the two-step workflow, when to call with only slug vs with tlumaczenia, and provides example queries. It also states what not to do ('Do not tell the user the translations are already on the page').

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 destructiveHint=false, and the description reinforces this with a plain 'Read-only.' Beyond the annotations, it explains output content (e.g., 'state (published, or rejected with the reason)') and the tool's role as a prerequisite for other tools, adding useful behavioral context without needing to repeat safety metadata.

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 primary action and output fields, followed by a crisp 'Read-only.' and the crucial first-step note. The three example questions are helpful but slightly redundant—they restate use cases already implied—yet they do not bloat the text excessively.

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 parameters, no output schema, and full annotation coverage, the description is complete: it tells the agent what the tool does, what results to expect (fields include slug, state, rejection reason), and when to invoke it. An agent can decide to call this first without needing additional details.

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?

There are zero parameters, so the empty schema already fully describes the input contract. The description adds no parameter details because none exist; per rubric, a zero-parameter tool receives a baseline of 4, as the description cannot add 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?

The description states a specific action ('List this account's games') and a clear resource ('klyo games catalogue'), and enumerates the returned fields (name, slug, state, size, visits, plays). It differentiates from siblings by positioning itself as the tool to call FIRST to obtain the slug needed by other tools, so an agent can distinguish it without opening schemas.

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

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

The description gives explicit when-to-use guidance: 'Call this FIRST to learn the `slug` the other tools need.' This clearly places it before other catalogue tools, and the example questions illustrate typical use cases. It does not name dispreferred alternatives or conditions to avoid, hence the absence of 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?

Annotations flag a non-read-only, non-idempotent, open-world write, and the description adds substance beyond that: the package is downloaded and checked for size, files, third-party ads, malicious code, profanity and other companies' brands; the game lands in a waiting state at g-<slug>.klyo.pl; owner approval is required before 'Release'. These are real behavioral traits not captured by the annotations.

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

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

The purpose is front-loaded and most sentences carry distinct information, with the critical 'IT DOES NOT PUBLISH' constraint given prominence. It is dense and occasionally crams several rules into one sentence (limits plus language rules plus address derivation), but the length is largely justified by a 29-parameter, nested-schema tool.

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

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

There is no output schema, so the description carries the return-behavior burden and does so: it explains the resulting state (`oczekuje`), the generated address (g-<slug>.klyo.pl), and that the owner sees review evidence before release. Combined with full param coverage and a clear mutation/approval workflow, an agent has what it needs to call this correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 29 parameters in detail. The description adds cross-parameter constraints (name ≤30 chars, tagline ≤80, English description required with 25-word minimum and ~220 for indexing, all ten questionnaire answers, seven review points) but largely restates what the schema fields carry.

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 ('Prepare a browser game for release on games.klyo.pl') and names related siblings (klyo_upload_package, klyo_game_translate, klyo_game_diagnostics). It does not explicitly distinguish itself from the closest functional siblings klyo_update_game and klyo_fill_game_form, though the 'studio wizard' framing implies a creation flow rather than an edit.

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 the prerequisites (owner must have accepted developer terms at dev.klyo.pl), what the tool explicitly does NOT do ('IT DOES NOT PUBLISH', game sits in `oczekuje`), what to tell the user instead, when to include `przeglad` (stage `gotowa` or none), and which sibling to call for translation and diagnostics. This is unusually complete routing guidance.

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

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the description doesn't need to restate those. It adds valuable behavioral context: the previous version's files are kept next to current ones, rolling back again swaps them, and the game's address/scores/stats do not change. It also discloses the refusal condition (brak_poprzedniej). This goes beyond the annotations and helps the 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 a single paragraph with a clear first sentence stating the action, followed by behavioral details and a usage scenario. It is front-loaded and every sentence adds information. It could be slightly more concise, but the length is justified by the need to explain the swap behavior and error condition.

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 tool with no output schema, the description covers the action, side effects, error condition, and a recommended workflow. It doesn't describe the return value or output format, but since there is no output schema and the tool is a mutation, that is a minor gap. The description is complete enough for an agent to invoke it correctly.

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

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

The schema already covers the single parameter (slug) with a description, so baseline is 3. The description adds context by explaining that slug is the game address in the catalogue and referencing klyo_my_games as the source, which helps the agent know where to get the value. This is a modest but real addition 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 states the tool rolls a game back to the previous version, identifies the resource (game slug), and distinguishes it from related operations like klyo_release_version. It also explains the mechanism (files kept, switch without uploading) and the error condition, making the purpose 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 explicitly says when to use it: when the owner reports a new version breaks the game. It also provides a workflow after rollback (fix locally, run klyo-test, klyo_update_game, klyo_release_version), which is strong usage guidance. It doesn't explicitly name alternatives, but the context and workflow make the appropriate use 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 minimal annotations, the description discloses rich behavioral effects: players immediately get the new version, mid-round players see an update bar, the previous version stays, the game page is rebuilt, followers are notified, and clip behavior changes per `zmiana` type. It also describes the review re-check before the swap. This is exactly the kind of context annotations cannot convey.

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

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

The description is long but well-organized: core operation, then parameter effects, then gating conditions, then the review requirement, then examples. Some material repeats schema content, but for a complex release operation that reinforcement is useful rather than wasteful.

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 fully covers what the agent needs to call the tool correctly: the prerequisite (waiting version from klyo_update_game), the eligibility condition (owner confirmation), when evidence is required, and all user-visible side effects. Nothing critical for 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 schema already provides detailed parameter descriptions and covers 100% of parameters, so the baseline is 3. The description adds value by explaining the default for omitted `zmiana`, the clip consequences for each change type, the `nowosc` feed behavior, and the condition under which `przeglad` is mandatory.

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 action on a specific resource: 'Release to players the version waiting after klyo_update_game (`slug`)'. It clearly identifies this as the update-release step and distinguishes it from other game lifecycle tools by pointing at the upstream update tool.

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

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

It gives clear usage context: this tool is for releasing the waiting version after an update, and only when the owner has played the new version or deliberately waived that. It also states when a premium review is required. However, it does not explicitly tell the agent when not to use it or name alternatives such as klyo_publish_game or klyo_release_rollback.

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 read-only/idempotent/no-destructive hints. The description adds value by specifying the payload contents (server version, key scope, account role, tool count, write permission) and the semantics of integration statuses (`ok`, `not_connected`, `auth_error`, `no_data`) plus embedded remediation guidance. It does not contradict annotations.

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

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

The description is dense but arguably a little padded: 'Read-only' duplicates the annotation, and the three example questions are helpful but not strictly necessary. Core purpose and usage are front-loaded, and each remaining sentence contributes unique information.

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

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

For a zero-parameter read-only status tool with no output schema, the description fully covers what the agent will receive and when to call it. It includes the list of integrations, possible status values, and directs the agent to use it before critical decisions. 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 tool takes zero parameters, and the schema has no properties, so there is no parameter-level semantics to document. Baseline 4 for 0-param tools; the description appropriately focuses on output and usage instead.

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: it reports the state of the klyo connection, enumerating server version, key scope, account role, tool count, write permission, and integration statuses with action items. The example questions make it unambiguous that this is a status/health-check tool, clearly distinct from the mutating 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?

Explicitly instructs to call it at the start of work and before relying on a possibly-unloaded report section, giving clear timing. It does not name alternatives or when-not conditions, but the sibling set makes the status role obvious and the examples reinforce the intended use 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 establish that this is a mutating, destructive, non-read-only tool, and the description adds substantial side-effect detail beyond that: a published game does not change immediately, the new version replaces any version already waiting in the waiting room, an unpublished game gets the new files at once, and a human must record the clip. No contradiction with annotations exists.

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

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

The description is long but appropriately dense: the main operation is front-loaded in the first sentence, and subsequent sentences each add critical workflow, side-effect, or exclusion information. The natural-language examples are compact and help an agent recognize user intent. 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 complex mutation with no output schema, the description covers almost everything an agent needs: inputs, when changes become visible, the waiting-room replacement behavior, the zmiana response field, the release workflow, and the human-only clip recording. The main gap is that it never crisply states the one-of-upload_id/zip_url requirement or the behavior if both are supplied, which is a small but real omission.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does reinforce the file-vs-url source choice by mentioning klyo_upload_package and 'public zip_url', but it mostly restates the schema fields. It does not explicitly state that exactly one of upload_id or zip_url should be supplied or what should happen if both are provided, so it adds only moderate 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?

The description opens with a concrete verb and resource: 'Upload a NEW VERSION of a game that is already on the account (`slug`)' and then names the two allowed package sources. It clearly differentiates this action from related siblings by stating the game 'keeps its address, name, description, scores and hearts; only the files change', which is not a tautology.

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 when-to-use guidance: 'Do not create a second game to ship a fix: that splits players and records between two addresses.' It also explains the staged workflow, names klyo_release_version as the alternative release path, and notes when upload_id is preferred over zip_url. An agent gets clear decision rules rather than having to infer them.

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

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

Annotations are minimal (only four boolean hints), so the description carries the burden — and it delivers richly: the ticket is valid for one hour ONLY, opens no tool, must not be saved in project files, uploads land in a waiting room with nothing published, and the tool must be called again after manual upload. This far exceeds what the annotations disclose.

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 purpose and well-structured via a numbered three-part return list and a clear recipe. It is long (~230 words) and contains some parenthetical asides that could be tightened (e.g., 'it opens no tool; you do not have it in your configuration, which is why you get it here'), and the four examples slightly repeat stated use cases — but nearly 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?

With no output schema, the description must explain return values, and it does comprehensively: all three returned items, the ticket's purpose and expiry, two execution paths (curl vs. owner upload), the re-call flow, and integration with sibling tools. The full lifecycle from disk file to publishable upload_id is covered with no critical gaps.

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

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

With 0 parameters, the baseline is 4 and there is nothing for the description to explain about schema fields. It does add useful invocation semantics by specifying where the returned ticket goes (Authorization: Bearer header) and what upload_id is for, which is context the empty schema cannot convey.

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

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

The opening sentence states a specific verb and resource: "release a game from a file on disk, with no tunnel and without exposing an unreleased game publicly." The title reinforces the differentiator ('no public URL needed'), and the description names klyo_publish_game/klyo_update_game as the next step, making clear this is the disk-upload entry point rather than a publish/update tool.

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

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

The description explicitly routes the agent: pass the returned upload_id to klyo_publish_game or klyo_update_game instead of zip_url, and call the tool again after the owner uploads manually. The four examples map directly to trigger scenarios (disk file, owner uploaded in studio, avoid public exposure), leaving no ambiguity about when to choose this tool.

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