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

Goes well beyond the annotations by explaining that API keys are bound to a single account and that all other tools implicitly operate on whichever account is active — the key operational consequence an agent must know. It also discloses the switch side effect, including the device-login branch (show the URL and code, then call gamealia_login with wait:true) and that list changes nothing, which complements rather than contradicts the supplied hints.

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

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

Three sentences, front-loaded with the resource and scope, then the operational constraint, then per-action detail. Dense but readable; the role enumeration ("owner, admin, developer or finance") is arguably more detail than an agent needs to pick the tool.

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

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

For a two-action tool with no output schema, this covers the identity/auth model, the side effect of switch, the follow-up call required after a device login, and the data returned by list. Nothing needed to invoke it correctly is missing.

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

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

Every parameter is already documented at 100% coverage, so the schema baseline is 3. The description earns one more point by describing the outcome of each action — what list returns (id, name, individual/business, role, active flag, pending invites) and what switch does with a stored key versus a device login — rather than restating the enum.

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?

"Lists or switches the user's Gamealia developer accounts" is a specific verb+resource pair, and the parenthetical "their own and studios they joined" narrows the scope. It also establishes the distinguishing fact that every other tool acts on the active account, which implicitly separates it from gamealia_login and gamealia_whoami, though those siblings are never named.

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 a concrete decision rule for the 'before' case: when the user has several accounts, confirm the right one before creating or publishing games. The list-vs-switch split is spelled out. It stops short of naming alternatives or saying when this tool is not appropriate.

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 openWorldHint=false, so the bar is lower; the description still adds meaningful context by stating 'runs nothing, no login' and that the result names the next step. It doesn't detail output structure, but that is covered by the output 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?

Front-loaded with the core action before the enumerated detection list, and every item conveys a distinct capability. It is dense and long for a single sentence, but no clause is wasted.

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

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

Given a single fully-documented parameter and an existing output schema, the description covers everything an agent needs: what it inspects, that it is safe, when to call it, and what comes next.

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?

Only one parameter and schema description coverage is 100%, so the schema already fully documents 'dir'. The description adds no further meaning about path resolution or edge cases, so baseline 3 applies.

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

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

States a specific verb ('Inspects') and resource ('a local game folder') and then enumerates exactly what it detects: engine, build command, output dir, entry html, SDK usage, policy problems, storage keys, size, and permissions. This is precise enough to distinguish it from sibling tools like gamealia_check_integration or gamealia_build.

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 'Call it first on an existing game', gives the alternative for the no-game case (gamealia_create_project), and names the typical follow-up (gamealia_integrate_sdk). Both the when-to-use and the sibling routing are covered.

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 it is not read-only, is idempotent and non-destructive; the description adds duration ('may take minutes'), progress notifications, the return payload (output folder plus last log lines), the failure mode (error with end of the build log), and the no-build-step no-op. That is substantial 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?

Two sentences, front-loaded with the action and outcome, and no filler. The first sentence is long with stacked parentheticals, which slightly hurts scannability, but every clause carries 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?

With no output schema, the description correctly carries the return-value burden (folder plus log tail, error text on failure) and covers timing and notifications. It does not mention what build artifacts or files are written to disk, a minor gap for a mutating tool with destructiveHint=false.

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 is only one parameter, dir, and schema coverage is 100% with its own description of absolute vs. relative paths. The description adds nothing about the parameter, so this sits at the 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?

States a specific verb and resource ('Runs the project's detected build command locally') plus the outcome returned (output folder and log tail). It also handles the edge case where no build step exists, and names the siblings it overlaps with, so the agent can tell it apart from gamealia_run_autotest, gamealia_preview and gamealia_upload_version.

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 states that it is 'usually optional' because the autotest, preview and upload tools build first by themselves, then gives the one condition that selects it: debugging a failing build. This is exactly the when-to-use vs. when-not-to-use routing 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description reinforces this with "no browser, no login". It also adds real behavioral context about severity levels (pass/warn/fail), fix messages, and file:line output, and notes it is a static (non-executing) check. However, with an output schema present, restating the return shape is largely duplicative, so the net addition beyond structured data is moderate.

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

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

Front-loaded with the core action and the read-only/no-login constraints, then the check list, then timing, then return shape. Dense but well ordered; the long enumeration of checks is justified because it defines scope, though the sentence is heavy.

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 read-only lint tool, the description covers purpose, scope, sequencing relative to siblings, and severity semantics, while annotations carry the safety profile and the output schema carries the return structure. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema description coverage is 100% and both parameters (dir, backendHosts) are fully documented in the schema, so the baseline is 3. The description does not explain dir resolution or how backendHosts changes which hosts are flagged; that detail lives only in the schema.

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

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

States a specific verb and resource ("Fast static lint of a local project's source or build") and then enumerates exactly what is checked: SDK load/call, loadingStop/gameplayStart, locale handling, no external ads/trackers, no purchase UI, build security, sizes. That enumeration makes it unmistakable next to siblings like gamealia_analyze_project or gamealia_run_autotest.

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 workflow placement: after gamealia_integrate_sdk and before the slower gamealia_run_autotest, with the speed tradeoff stated ("slower"). An agent knows both the trigger point and which sibling to defer to when a full run is needed.

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 non-readonly, non-idempotent, non-destructive, open-world, but the description adds concrete substance beyond them: login is required, a taken slug fails (matching non-idempotent), cover/thumbnail uploads are side effects, and the game remains a draft and non-public until a version is approved. It even discloses the return shape (id, slug, status).

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

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

Front-loaded with the action and the critical non-idempotent/login caveats, and the sibling references are placed usefully. It is a dense semicolon-chained paragraph, though, so the field list reads as a run-on rather than a scannable structure.

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

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

For a 14-parameter, mutation-heavy tool with nested locales and no output schema, the description covers prerequisites, side effects, draft visibility, return values, and follow-up steps. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds value by summarizing the es/en title/description/controls, tags, orientation, multiplayer, ads, backend hosts, permissions, and the optional cover/thumbnail paths, giving an agent a coherent overview before it opens each parameter.

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

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

States a specific verb and resource ('Creates a new game listing in the active developer account') and immediately lists the fields it owns. It differentiates itself from gamealia_update_listing, which it names explicitly for the update case.

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

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

Explicit sequencing: call once per game, after gamealia_run_autotest passes, and use gamealia_update_listing for existing listings. It also names gamealia_generate_cover for producing the optional images and points to gamealia_upload_version as the next step, leaving little to inference.

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

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

Annotations only declare the safety profile (not read-only, not destructive, not idempotent, closed-world); the description adds what they cannot: writes to local disk only, requires no login, aborts on a non-empty folder, and returns the written files. The per-template build semantics (no build step vs. `npm install && npm run build` -> dist/) are behavioral detail an agent needs before scaffolding.

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

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

Purpose and the alternative-routing sentence are front-loaded, and every following sentence adds a distinct fact (local-only, overwrite guard, return value, template table). The nested parentheticals in the template list are dense and occasionally run-on, costing a point on readability but not on substance.

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

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

For a three-parameter scaffolding tool with no output schema, the description still covers return content ("Returns the files written"), auth posture, failure mode, and post-scaffold build steps per template. Nothing an agent needs in order to call it correctly or interpret the result 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 already documents dir, title bounds, and the template enum with a default, so the baseline is 3. The description earns an extra point by explaining the consequences of each template choice (plain JS vs. Vite build output vs. BroadcastChannel multiplayer stand-in), which the enum list alone does not convey.

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

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

"Scaffolds a new minimal game, already integrated with the Gamealia SDK, into an empty or new folder" gives a specific verb, artifact, and target, and the "local files only, no login" clause separates it from the account-bound siblings. The explicit contrast with gamealia_analyze_project + gamealia_integrate_sdk makes it distinguishable without opening either schema.

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

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

States the trigger condition ("when there is no game yet") and names the two-step alternative it replaces, which is exactly the routing decision an agent faces. The guard "Never overwrites: fails if the folder has any file" tells the agent when the call will not succeed, which is a usage constraint, not just a behavior.

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 readOnlyHint and openWorldHint=false, the description discloses that the corpus is bundled locally, that authentication is not required, that search results are locale-sensitive with English fallback, and exactly what a result contains (slug, title, uri, snippet). The read:true escape hatch for fetching top-page markdown is also explained, which the annotations alone could never 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?

Purpose and scope are front-loaded in the first clause, followed by when-to-use and then return behavior — a good information order with no filler sentences. It is dense, packing corpus, permissions, locale behavior, and retrieval paths into two long sentences with several parentheticals, which costs a little readability but wastes no content.

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

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

For a 3-parameter read-only search, the description covers the corpus, preconditions, locale fallback, result shape, and the follow-up action for full page content. Even though an output schema exists, the description still tells the agent enough to chain a search into a page read without further discovery.

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 three parameters are already documented in the schema, making 3 the baseline. The description restates the read:true behavior and the locale fallback rather than adding new semantics — it clarifies that read only returns the *top* page, but the schema's "best match" already implies this.

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 ("Searches the Gamealia developer docs bundled with this server") and enumerates the covered content (SDK reference, publishing requirements, autotest checks, reject reasons, guides). No sibling tool does documentation lookup, so the scope statement alone distinguishes it from the build/test/publish tools in the list.

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

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

Gives an explicit trigger ("Use it before guessing an SDK call, a policy rule or how to fix a failed check"), which ties directly to the failure modes of sibling tools like gamealia_check_integration or gamealia_run_autotest. It also names the alternative retrieval path (read the resource gamealia://docs/<slug>) and the preconditions (local, read-only, no login needed), so an agent knows when to call it and what to do afterwards.

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

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

Goes well beyond the annotations (destructiveHint/openWorldHint) by naming exactly what gets written, that existing cover/thumb files are refused unless overwrite:true, that uploads replace the listing's current images, and that the game path requires login. It also discloses the return payload: file paths plus the cover as an image.

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 load-bearing, with the core action front-loaded before side effects and routing. Dense nested parentheticals (e.g. the screenshot example and the overwrite caveat) slightly slow scanning but carry genuine 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?

With no output schema, the description supplies the return shape itself (paths plus cover image), plus overwrite semantics, login requirement, and upload side effects. Nothing an agent needs to invoke this safely and correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, and the description adds real meaning: an example screenshot value tied to gamealia_run_autotest, the outDir default behavior, and the consequence of overwrite:true. It stops short of clarifying formats or constraints on title beyond what the schema states.

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 concrete outputs: makes a 1200x630 cover and 512x512 thumbnail from a gameplay screenshot, center-cropped with the title on a gradient. It also names the downstream siblings (gamealia_create_game, gamealia_update_listing), so an agent can place it precisely in the workflow.

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 branches usage: omit `game` for local-only generation, pass `game` (requires login) to also upload and replace listing images, and otherwise hand the resulting files to gamealia_create_game or gamealia_update_listing. When-to-use, when-not, and alternatives are all present.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds the substantive behavior: authentication requirement, meaning of the role-forbidden failure, and the exact shape of the returned data (balance, per-month estimated/confirmed amounts, adjustments, revenue share %, payouts with date/amount/method). The unit disclosure (USD, micro-dollars via balanceMicros) is real behavioral context the annotations cannot carry.

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

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

Front-loaded with purpose and safety/auth context, then the return shape, then the sibling redirect. It is a single dense run-on with heavy parenthetical enumeration, which costs a little readability but every clause (units, scope, error meaning) 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?

There is no output schema, so the description carries the burden of describing return values and does so concretely, down to units and the balanceMicros field. Combined with the auth and error semantics, nothing an agent needs in order to call it correctly or interpret a failure is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline applies. It does not waste space re-explaining an empty input schema.

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

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

States a specific verb and resource ("Returns the active developer account's earnings") plus explicit scope: account-wide, not per game. It names the sibling gamealia_get_stats and the data that belongs there (plays, ad impressions), so an agent can distinguish the two without opening either schema.

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

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

Explicitly routes the agent: use this tool for account finances, use gamealia_get_stats for per-game plays and impressions. It also gives prerequisites ("needs login") and an error-interpretation rule ("a role-forbidden error means the user's role cannot see finances"), which covers the when-not case.

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 openWorldHint=true, so the description only needs to add context; it does so by stating the login prerequisite, which is an auth requirement not present in the annotations. It stops short of noting rate limits, whether 'totals' cover the full lifetime or just the window, or how days interacts with the returned granularity.

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: a dense front-loaded payload description followed by routing guidance. The metric enumeration earns its place and includes the useful unit note (playtime in seconds), though the list is long enough that a reader must parse past it to reach the tool-selection 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?

With no output schema, the description must carry the return contents, and it does by listing the metric families. For a simple two-parameter read tool that is largely sufficient; remaining gaps are minor, such as whether totals span the requested window or the full history and whether data is bucketed per day as the name implies.

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

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

Schema coverage is 100%, and the schema already documents both game (slug or id, from gamealia_list_games, active account) and days (1-365, default 30) with bounds. The description only echoes 'last N days' and 'one game's', adding no format or constraint detail beyond structured fields, 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 (returns one game's daily stats plus totals), enumerates the metric families returned (plays, players, playtime, device split, ad requests/impressions), and explicitly names the scope of a single game over the last N days. It is clearly distinguishable from siblings like gamealia_get_earnings and gamealia_get_status, which it names directly.

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

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

Gives an explicit use case ("see how a live game performs") and routes the agent away with named alternatives and their conditions: money -> gamealia_get_earnings, review state -> gamealia_get_status. An agent can pick between the three without opening any schema.

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?

Read-only is already covered by readOnlyHint, but the description adds genuinely new behavioral facts beyond the annotations: login is required, and the returned status is enumerated as one of draft/live/unlisted/banned so the agent knows the value space. It does not discuss rate limits or pagination, but those are minor for a single-game read.

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, front-loaded with the core purpose before the mode-switching clause, and every enumerated item is a real field the caller gets back. The first sentence is long and list-heavy, which costs a little scanability, but nothing is padding.

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

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

For a 2-parameter read tool with a full output schema, the description covers purpose, auth requirement, timing, and the alternate mode's contents. Since the output schema documents return shape, omitting return-value format details is fine; only the absence of sibling comparisons keeps it from being 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, and the description earns the extra point by expanding the meaning of the texts flag well past the schema: it returns per-locale listing text statuses (developer-written, machine-translated, missing), the source text to translate from, and the field limits. That tells the agent what the flag actually activates, not just that it includes texts.

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 precise verb+resource ("Shows where one game stands") and then enumerates exactly what is reported: listing status, live version, requested vs live permissions, latest version state, autotest report, reject reasons, previous version states. That enumeration clearly separates it from siblings like gamealia_list_versions (version list only) and gamealia_list_games (game list only).

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?

"Use it after uploading or submitting, and to read a rejection" gives concrete triggering moments, and the "texts:true instead returns..." clause explains when to switch modes. It stops short of naming explicit alternatives to avoid (e.g. list_versions for a bare version list) or stating exclusions, so it is clear context but not full when/when-not 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?

Goes well beyond the supplied annotations (destructiveHint=true, idempotentHint=true) by disclosing that dry run is the default, that every changed file is backed up first, that unparsable files are left alone, that merges are idempotent, and that `gamealia agents uninstall` reverts the whole thing. It also names the exact files and directories touched per scope, which is the kind of detail 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 key framing — one-time setup, dry run by default, returns snippets — is front-loaded in the first two sentences, and the remaining parenthetical lists earn most of their space by naming concrete config paths. It is dense and slightly over-long, with the agent-name enumeration and file lists bordering on clutter.

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 still explains the return value (planned file changes plus copy-paste snippets like `claude mcp add`, Codex TOML, and install links). It also covers safety (backups, unparsable files untouched), reversibility, and per-scope effects, which is everything an agent needs before invoking a destructive write tool with zero required parameters.

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

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

Schema coverage is already 100%, so the baseline is 3; the description adds value by spelling out the practical consequences of scope ('project writes .mcp.json, .claude/skills, .cursor/ ...; global edits ~/.claude.json, ~/.codex/config.toml, Claude Desktop') and by pairing write:true with 'applies'. That said, much of the scope and write semantics is already stated in the schema property descriptions, so it is reinforcement rather than entirely new meaning.

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

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

States a specific verb and resource ('registers this MCP server and installs the Gamealia skills/rules in coding agents') plus an explicit scope exclusion ('One-time setup, not part of publishing'). This clearly separates it from the publishing siblings and from gamealia_integrate_sdk, which targets SDK code rather than agent configs.

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?

Frames the situation ('One-time setup, not part of publishing') and explains the dry-run-by-default workflow with write:true as the apply switch. It does not explicitly name a sibling to use instead, such as gamealia_integrate_sdk for SDK work, so a small inference is left to the 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 flag destructiveHint=true and idempotentHint=true, but the description adds real substance beyond them: the default is a non-mutating dry run returning a unified diff, write:true is the mutating path, the operation is deterministic and idempotent, and it returns file:line TODOs. It could go further on what exactly is overwritten in pre-existing project files, which matters given destructiveHint=true.

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

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

Front-loaded with the action and prerequisite, then conditions, then return values, then the next step — a logical order with no filler. It is a dense semicolon-chained paragraph, though, and the TODO/next-tool information could be split for faster scanning.

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 contract: a unified diff in dry-run mode and file:line TODOs for hand-placed calls. Combined with the prerequisite, the write switch, and the follow-up tool, an agent has everything needed to call this correctly and interpret 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% and both parameters are already documented, including write's default-false dry-run meaning. The description restates the dry-run vs write:true distinction but adds no new syntax, path rules, or edge-case behavior for `dir` (e.g. what happens if it isn't a recognized project). Baseline 3 applies when the schema carries the 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?

States a specific verb and resource ("Patches a local project to use the Gamealia SDK") and immediately scopes it relative to siblings: it runs after gamealia_analyze_project and before gamealia_check_integration. It also enumerates the concrete edits (script tag/import, lifecycle adapter, SDK swaps, Unity .jslib / Godot addon), so an agent can distinguish it from analyze/check tools without reading 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?

Gives explicit sequencing ("after gamealia_analyze_project", "then run gamealia_check_integration") and explains the mode split: dry run by default, write:true to actually edit. The division of labor is spelled out — the tool places the plumbing, while gameplayStart/Stop, happyTime and ad breaks are left as TODOs for the 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?

The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered; the description only adds 'needs login', which is genuinely useful context beyond the annotations. It also discloses that all games are returned with no filtering/pagination, but says nothing about error behavior or what happens with an expired session.

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

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

Front-loaded with the core action and account scope, then the returned fields, then usage routing; every clause carries information an agent needs. No filler, no 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?

With no output schema, the description correctly compensates by enumerating the return fields, and it flags the login prerequisite. Only minor gaps remain (no mention of ordering, empty-account behavior, or pagination limits) for what is otherwise a simple zero-parameter read tool.

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

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

The tool takes zero parameters, so there is no parameter semantics to document and the baseline of 4 applies. The description does not waste space inventing parameter detail, instead spending its words on scope and return values.

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

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

States a specific verb and resource ('Lists every game of the active developer account') and immediately enumerates the returned fields (slug, title, status, live version id, cover/thumbnail URLs), so the agent knows exactly what it gets. It is clearly distinguishable from siblings like gamealia_get_status and gamealia_list_versions, which the description explicitly delegates to.

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 two concrete when-to-use cases ('find the slug the other tools take', 'check that a game exists before gamealia_create_game') and names the alternative for a different need ('for one game's versions and review state use gamealia_get_status'). This is explicit routing, not implied guidance.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds genuinely new context: login is required, results are ordered newest-first, and the state vocabulary (uploading, testing, tested, awaiting_review, approved, rejected, archived) is disclosed. It stops short of covering pagination or behavior when the game slug is invalid, which keeps it below a 5.

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, front-loaded with the core action and ordering, then the routing hint. The long parenthetical field list is dense but each item describes a returned attribute an agent would otherwise have to discover by calling; only the trailing "..." in the state list is slightly loose.

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 correctly takes on the burden of describing return contents, and it does so thoroughly, including auth and ordering. Minor gaps remain around result volume/pagination and error cases for an unknown game, which matter for a list 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% and the single `game` parameter already documents that it accepts a slug or id from gamealia_list_games. The description adds no syntax or format detail beyond that, so this sits at the baseline where the schema does the work.

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

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

States a specific verb and resource ("Lists all versions of one game") plus ordering ("newest first") and enumerates exactly what each entry contains (number, state, live flag, release notes, size, autotest status, reject reasons). It also names the sibling it is not (gamealia_get_status), so an agent can separate the two without opening either schema.

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

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

Gives an explicit routing rule: use this for the version list, but use gamealia_get_status for the latest version's full autotest report and the next step. It also states the prerequisite ("needs login"), so an agent knows when the call is even viable.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=true; the description goes far beyond that by disclosing the out-of-band approval flow (URL plus code, Google or email/password), profile auto-creation, background polling, and a concrete side effect with location and permissions (API key written to ~/.config/gamealia/credentials.json, mode 600). It also bounds each wait call at 50 s and explains the repeat-while-pending loop, which an agent needs to avoid misreading a pending response as failure.

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

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

Front-loaded with the ordering constraint and mechanism, and every clause carries information (flow, file side effect, timeout, idempotency, override). It is a dense run of parentheticals in one paragraph; breaking the wait/force behavior into a separate sentence would improve scannability without losing content.

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-value burden and does: URL and code on first call, username when already authenticated, pending state implied by the wait loop. Combined with the disclosed credential file side effect and the 50 s bound, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds operational meaning the schema does not: wait is a polling loop with a ~50 s ceiling per call that must be repeated, and force discards an in-flight login. That is behavior beyond the terse schema strings, though neither parameter's interaction with the logged-in shortcut is spelled out in full.

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 ("logs in to Gamealia") plus the mechanism (device code), and immediately distinguishes its role from all siblings: "call it first, since every tool that talks to Gamealia needs it." An agent can place this tool relative to gamealia_whoami, gamealia_logout, and the rest without opening any schema.

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

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

Gives explicit when-to-use (before any Gamealia call), explicit follow-up behavior ("call again with wait:true ... repeat while still pending"), explicit override conditions ("unless force:true"), and the already-logged-in case. Alternatives and exclusions are both named rather than inferred.

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

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

Annotations flag destructiveHint=true and idempotentHint=true, but the description goes well beyond them by naming exactly what is destroyed (the local credentials file, every stored account key), what is not (the server-side key is not revoked), and the interaction with GAMEALIA_API_KEY keeping calls authenticated. That is precisely the context an agent needs before a destructive 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?

Three short sentences, front-loaded with the action and its effect, then the server-side caveat, then the environment-variable nuance and the alternative. 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 zero-parameter, no-output-schema tool, the description covers the destructive effect, recoverability posture (key not revoked), idempotency, environment interaction, and the alternative tool. Nothing material to calling it correctly is missing.

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

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

The tool takes no parameters, so the schema imposes nothing to explain and the description correctly spends no words on inputs. It uses the space instead for behavioral caveats, which is the right allocation.

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 scope ("Logs out on this machine") and immediately specifies the mechanism: deleting the local credentials file and cancelling a pending login. Explicitly says it is local only, which distinguishes it from any server-side session concept and from siblings like gamealia_login.

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 a concrete routing rule: "To change account, use gamealia_accounts instead," naming the alternative and the condition that selects it. Also clarifies that repeating is safe. It stops short of stating when logging out is unnecessary or undesirable, so it is clear rather than exhaustive.

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 it is a non-read-only, non-open-world, non-idempotent operation, but add nothing about constraints. The description supplies the real operational facts: an implicit build step (unless build:false), a returned session id plus first screenshot, a 40-action cap per session, 2 concurrent sessions, idle auto-close after a few minutes, and no login required.

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 key fact (starts the game for manual play) is front-loaded and every sentence carries information: purpose, workflow, limits, environment. It is densely packed with parentheticals and semicolon chains, which costs a little readability but no sentence is wasted.

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

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

For a session-starting tool with no output schema, the description covers what an agent needs: what is returned, which siblings continue the workflow, hard limits, session lifetime, and that no auth is involved. Nothing required to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already explains dir, build, and the desktop/mobile profile enum; baseline is 3. The description adds only one detail beyond the schema — that the build runs first unless build:false — and says nothing about profile differences (viewport/touch behavior) that would help an agent choose.

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 ("Starts the game ... in headless Chromium inside the autotest harness so you can play it yourself") and explicitly distinguishes it from the sibling gamealia_run_autotest by naming the case it can't cover ("gameplay the automatic gamealia_run_autotest cannot judge"). An agent can tell it apart from gamealia_preview and gamealia_run_autotest without opening any schema.

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

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

Gives the when-to-use condition (manual gameplay judgment the autotest can't make) and the full lifecycle: call gamealia_playtest_act one action at a time, then gamealia_playtest_stop for the verdict. It also names the action vocabulary (click x,y | key | drag | wait), removing ambiguity about what happens next.

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

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

Goes well beyond the annotations: annotations only say it is a non-readonly, non-idempotent, non-destructive write, while the description discloses exactly what comes back (new screenshot, step number, steps left, SDK calls since last step, new console errors, ad requests, frame-change percentage), the serialization constraint, and the expiry failure mode. The heuristic that '0% often means the input did nothing' is genuinely useful diagnostic context an agent could not get from structured fields.

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

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

Front-loaded with the verb and scope, then sequencing, then return payload, then failure/next-step — a logical order with no filler. The return-value sentence is a long comma-separated list, but since there is no output schema each item earns its place; only minor tightening (e.g. grouping the telemetry fields) is possible.

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 interaction tool with no output schema, the description supplies the missing return-value contract, the failure modes, the concurrency/ordering model, and the follow-up tool. Nothing an agent needs in order to call this correctly, or to interpret the result, is absent.

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 description's action list ({type:...} variants) only restates what the oneOf branches and the action property description already document. No additional meaning such as coordinate origin conventions, key semantics, or sessionId lifecycle is added beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Performs one action ... in a session started by gamealia_playtest') and enumerates the four action kinds (click, key, drag, wait). It also positions itself relative to siblings by naming the session-starting tool and the stop tool, so an agent can distinguish start, act, and stop without opening any schema.

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

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

Gives explicit sequencing rules ('actions of one session run one at a time, in order'), an explicit failure condition ('fails if the session ended or expired'), and an explicit hand-off ('when steps run out, call gamealia_playtest_stop'). Both the when-to-use and the when-to-stop alternatives are stated rather than inferred.

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

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

Annotations only declare it is not read-only, not idempotent, and not destructive; the description adds substantive context beyond that — it waits for a pending action before closing the browser page, invalidates the session id, and terminates the browser. That invalidation detail is exactly the kind of consequence an agent needs before calling it, though it does not discuss failure behavior if the session is already gone.

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

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

Purpose is front-loaded in the first clause, side effects follow in parentheses, and the call-to-action closes the text. The enumerated return-summary list is somewhat redundant given an output schema exists and makes the first sentence long, but no sentence 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 single-parameter session-termination tool this covers the full picture: what it terminates, the sequencing behavior, the post-condition (session id dead), and when to invoke it. Return values are also sketched, so even without consulting the output schema an agent knows what comes back.

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

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

Schema coverage is 100% and the single parameter is documented as "Session id returned by gamealia_playtest", so the schema already carries the semantics. The description only indirectly reinforces this by noting the id stops working afterwards; baseline 3 applies when the schema does the work.

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 ("Ends a session started by gamealia_playtest") and explicitly names the sibling that creates the session, so an agent can pair playtest/playtest_stop without inspecting schemas. The parenthetical side effects and return summary further pin down what the tool is.

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?

"Call it when done playing, so the session does not hold a browser until it expires" gives a clear trigger plus the reason, and the opening clause ties it to sessions created by gamealia_playtest. No explicit when-not guidance is needed since no sibling competes for this job, but the exclusion case is left 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?

Beyond the annotations, it discloses the default build side effect, local 127.0.0.1 hosting, mock ads, absence of login or uploads, and the returned URLs. It also clearly documents the preview's persistent lifecycle, shutdown conditions, and same-folder restart 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?

The description front-loads the core action and outputs, then covers privacy, lifecycle, and alternatives in three dense but readable sentences. Nearly every clause supplies actionable information, with minimal 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 stateful local preview server with an optional build step, the description covers the essential setup, outputs, privacy characteristics, persistence, stopping, restarting, and alternative workflows. Although there is no output schema, the two returned URLs are explicitly identified.

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 operational meaning by connecting dir to same-folder restart behavior and explaining the effects of build:false and stop:true. It does not add anything about title beyond the schema, so this is strong rather than exhaustive parameter supplementation.

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 precisely states that the tool builds if needed, serves the project in a local Gamealia portal replica, and returns both the replica page URL and bare game URL. It distinguishes the tool from gamealia_run_autotest and gamealia_playtest by their respective purposes.

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

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

It gives explicit routing guidance: use gamealia_run_autotest for automated checks and gamealia_playtest to play interactively. It also explains when to use build:false and stop:true, and what happens when the tool is called again for the same folder.

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

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

Adds substantial behavior beyond the annotations: file side effects ('writes screenshots and report.json to a temp folder'), a duration warning with progress notifications ('takes a while'), a no-login auth note, and the shape of the result (pass/warn/fail plus failed checks with fixes). The write-to-temp-folder detail is consistent with readOnlyHint=false and non-destructive, and the no-progress-fast caveat is exactly the kind of operational 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?

Front-loaded with the action and scope, and every clause carries information: checks, viewports, ordering advice, side effects, duration, return shape. It is a single dense run-on paragraph heavy with parentheticals and semicolons, which costs a bit of scannability, but there is no filler to cut.

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 multi-step local test runner with four params, an output schema and annotations, the description covers the prerequisites (none/login), side effects, latency, and result interpretation that an agent needs to call it correctly, and it correctly does not re-document the return schema in detail. Nothing material is left to inference.

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

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

Schema description coverage is 100%, so all four parameters (dir, build, images, backendHosts) are already documented at the schema level, which sets the baseline at 3. The description reinforces only one of them ('unless build:false') and alludes to images via 'key screenshots as images', adding no syntax or edge-case 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?

States a specific verb+resource ('Builds ... and runs the full Gamealia autotest locally') plus scope detail that separates it from siblings: headless Chromium, desktop 1280x720 and mobile 390x844, and the enumerated check list (SDK lifecycle, blank screen, input response, ads, console errors, static security analysis). An agent can distinguish it from gamealia_build, gamealia_check_integration and gamealia_upload_version without opening any schema.

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

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

Explicitly routes ordering: 'Run it before gamealia_upload_version, which repeats it on the server,' which both names the alternative and explains the redundancy, plus 'No login' tells the agent no auth step is needed first. It stops short of stating when NOT to run it (e.g. skip after a successful local run) or pointing to gamealia_build/check_integration for partial checks, so it is strong but not fully exhaustive.

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 critical behavioral traits beyond the annotations, including failure conditions (no version tested, missing permission justification), operational prerequisites (needs login), and dynamic server responses (re-testing if permissions changed).

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 highly efficient, packing complex operational logic, prerequisites, and failure modes into a dense but logical paragraph. The structure follows a necessary workflow progression.

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 lacking an explicit output schema, the description explains what the tool returns (the version, awaiting_review) and outlines the subsequent steps (checking gamealia_get_status). All necessary operational context is present.

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

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

While the schema coverage is 100%, the description adds relevant context by specifying that 'notes' are intended for the reviewer, which provides semantic value beyond the raw schema definition.

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 (Submits), the resource (game version), and the context (manual review by Gamealia). It differentiates this operation from general version management tools by emphasizing the post-autotest state.

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 operational constraints, dictating when to call the tool (after user confirmation) and how it relates to other tools (must run after gamealia_upload_version, unless that tool already ran with submit:true).

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real substance: partial-update semantics (only given fields change), replacement semantics for permissions ('Replaces the current list'), the deferred effect of permission changes pending manual review, and the return payload (updated game plus permission changes). It does not flag irreversibility risks directly (e.g. slug being fixed once live is only in the schema) or failure modes, so it stops short of full 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 core action and replace-only-given-fields rule are front-loaded, then media, translation and permission caveats follow in a logical order. It is a dense, multi-clause paragraph that partially restates schema limits and the translate skill, but nearly every sentence carries operational information.

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

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

For a 15-parameter mutation tool with nested objects and no output schema, the description covers the essentials: auth requirement, partial-update behavior, media upload intent, multi-locale text handling, permission deferral, and the return values. The missing piece is guidance on precedence between texts and the top-level localized text fields, which an agent needs to avoid conflicting writes.

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 earns above that by explaining the intent behind coverPath/thumbPath (upload replacements) and the semantics of texts (multi-locale write, {} approves machine translation, null removes a locale, always wins over MT). The notable gap is that it never resolves the relationship between the top-level title/description/controls parameters and the texts object, which is the main ambiguity among 15 parameters.

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

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

The description opens with a specific verb+resource ('Edits an existing game's listing') and immediately scopes it: only supplied fields change, they replace current values, and coverPath/thumbPath upload new media. That cleanly separates it from siblings like gamealia_create_game and gamealia_upload_version without needing to name them.

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 login prerequisite, routes the agent to gamealia_get_status {texts:true} to read current texts and their status, and points to the translate-listing workflow before saving locales. It also warns that a permissions change only lands with the next approved version, implying the follow-up upload/submit calls. It does not explicitly say when to use this instead of create_game for a new listing, leaving that inference to the reader.

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, idempotentHint=false, openWorldHint=true), the description discloses login requirement, multipart/retry behavior, automatic abort of blocking interrupted uploads, server-side autotest waiting, and long runtime with progress notifications. It also confirms non-idempotence in plain terms ('each call creates a new version'), which is the practical consequence of the idempotentHint annotation.

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 action and its prerequisite come first, followed by side effects, runtime expectation, and the submit branch — a sensible order with no filler sentences. It is dense and somewhat long for a single paragraph, but every sentence carries operational information.

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

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

For a multi-minute, mutating, network-and-build pipeline tool with no output schema, the description covers what is produced (version state and autotest report), auth needs, failure/abort handling, and duration/progress signaling. An agent has everything needed to call it safely and set expectations for latency and side effects.

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 every parameter is already documented in the schema, including the noBuild default and the submit confirmation caveat, so the description adds little parameter-specific meaning. It does weave submit and noBuild into the workflow narrative (submission gated on autotest pass), but waitForPrevious and notes are not elaborated beyond the schema, keeping this at the baseline for full 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?

The description uses a concrete verb chain (builds, zips, uploads) against a specific resource (a new version of an existing game) and explicitly names the siblings it is not: gamealia_create_game (must come first) and gamealia_submit_for_review (the alternative to submit:true). An agent can distinguish it from build, run_autotest, and submit_for_review without opening any schema.

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

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

It states the prerequisite sequence explicitly ('Use it after gamealia_run_autotest passes locally and gamealia_create_game') and gives a conditional branch with an alternative ('submit:true ... only after the user confirmed; otherwise use gamealia_submit_for_review later'). When-to-use, when-not, and the sibling to use instead are all present.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds substantial behavior: the exact identity fields surfaced, that the API key is never returned (only its source: environment or credentials file), and that the call fails with a hint pointing at gamealia_login when unauthenticated. The one restatement of "read-only" is minor against the added security and error-path 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?

Front-loaded with the result contents, then scope, then the alternative, then the failure mode — a sensible order with no filler sentences. The parenthetical field list is dense but every item is informative, so it is length justified by content rather than padding.

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

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

There is no output schema, and the description compensates by enumerating what is returned, so an agent knows what to expect from the response. It also covers the unauthenticated failure case and the key-handling boundary, leaving no material gap for a simple identity-check 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 tool takes zero parameters, so there is nothing for the description to disambiguate; the schema is an empty object at 100% coverage. Baseline for a no-parameter tool applies, with no parameter-level meaning to add.

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 ("Shows who is signed in") and enumerates the returned fields: user id, username, developer profile existence, active developer account with role, API URL, and key origin. It also explicitly separates itself from the neighboring account tool ("to list or switch accounts use gamealia_accounts"), so an agent can distinguish it from siblings without opening a schema.

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

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

Gives an explicit when-to-use ("confirm the login before creating or publishing games"), names the alternative for a related need (gamealia_accounts for listing or switching), and names the recovery path (gamealia_login) when the call fails. When, when-not, and alternative are all present.

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