Playgama MCP - Publish & Manage HTML5 Games

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

Goes well beyond the annotations: one inviter per organization, immutable attribution, self-invitations refused, ALREADY_APPLIED retry semantics, bonus granted without starting a campaign, and a different invitation cannot replace an existing one. The retry-safe description sits in mild tension with idempotentHint=false, but the annotation's effect-based meaning (a second call with a different code is refused) is not directly contradicted.

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 timing constraint, and every subsequent sentence carries a distinct behavioral fact (immutability, retry behavior, recovery). It is dense and semicolon-heavy, but there is no filler to remove.

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

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

For a one-parameter irreversible mutation with no output schema, the description covers the eligibility window, the idempotent retry outcome, the ALREADY_APPLIED signal, the side effect (traffic welcome bonus, no campaign), and the state-recovery tool. An agent has enough to call it and to handle an ambiguous 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 description coverage is 100% and there is only one parameter, so the schema already carries the syntax and length constraints. The description reinforces that the value must be developer-supplied and used before first publication, but adds no format or URL-parsing detail beyond the schema.

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

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

States a specific verb (apply) and resource (referral code or invitation URL) and names the exact target (this organization before its first-ever Sandbox publication). It is clearly distinguishable from the sibling get_referral_program, which is presented as the read-side counterpart.

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

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

Gives explicit preconditions ('before its first-ever Sandbox publication'), an explicit prohibition ('Never invent a code'), and an explicit recovery path ('Read get_referral_program to recover state after an uncertain result'). The when-to-use and the alternative for the failure case are both stated rather than implied.

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

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

Annotations cover the mutation profile (readOnlyHint=false, destructiveHint=true), and the description adds substantial context beyond them: what is queued (unpacking, Bridge SDK analysis), that earlier archives are retained, that files land at a public archive URL for QA, and that it does NOT publish the sandbox page or catalog listing. The only wrinkle is the mild tension between 'Safe to repeat' and idempotentHint=false — retry-safety is not the same as idempotency, but the phrasing could be read either way, so it falls just short of 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?

Four dense sentences, front-loaded with the sequencing step, and each sentence carries non-redundant information (sequencing, effects, publication scope, error/idempotency, follow-up). Slightly packed, 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?

No output schema exists, yet the description covers the outcome (files available at a public archive URL), the boundary of the side effect (no sandbox page or catalog listing published), the 409 failure mode, retry behavior, and which sibling exposes the resulting state. An agent has everything needed to call this correctly and set expectations.

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

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

Schema description coverage is 100% and both parameters are documented there with provenance hints ('as answered by start_archive_upload', 'as returned by list_applications'). The description adds no parameter-level information, which is the correct baseline 3 when the schema already 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+resource ('adds the archive to the game's form', queuing unpacking and Bridge SDK analysis) and positions itself explicitly as 'Step 3 of 3, after the PUT'. An agent can distinguish it from start_archive_upload (the PUT) and get_archive_status (the polling view) 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 sequencing precondition ('after the PUT'), the failure condition ('Refused with 409 while nothing is uploaded'), and routes the agent to the alternative for follow-up ('keep polling get_archive_status'). This is explicit when-to-use and when-not-to-use guidance.

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

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

The description states 'Safe to repeat', which asserts retry/idempotency safety, while annotations declare idempotentHint: false — a direct conflict about what happens on a repeated call. The rest of the disclosure (409/422/502 semantics, the old cover being replaced, non-confirmation on 502) is genuinely useful and consistent with destructiveHint: true, but the retry claim is exactly the property the annotation denies, so an agent cannot trust it.

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?

One dense sentence, front-loaded with the workflow position and the action, then the validation performed, then the failure codes. Nothing is wasted, though the semicolon-chained clauses make it slightly 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 still covers the outcome ('publishes it and puts it into its slot', 'replaced' names the removed cover) and the principal error contract. Combined with annotations that already flag the destructive write, an agent has enough to call it correctly, apart from the unresolved retry semantics.

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

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

Both parameters have 100% schema coverage and the schema already says where each id comes from (start_cover_upload, list_applications). The description adds no further meaning to applicationId or mediaId, so the schema does the work; baseline 3.

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

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

Names a specific verb and resource (checks, publishes, and slots a cover file) and anchors itself in the upload workflow as 'Step 3 of 3, after the PUT'. It is unmistakable next to start_cover_upload, which begins the sequence, and it names the observable result ('replaced' names the cover taken out).

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 prerequisite (must follow the PUT), the failure modes that tell the agent what to do instead (409 when nothing is uploaded, 422 when the file does not fit, with the instruction to 'start a new upload'), and the retry posture ('Safe to repeat'). This is explicit when/when-not guidance rather than an implied use 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 carry readOnly=false, destructiveHint=true and idempotentHint=false; the description adds real context on top by explaining the non-idempotency rationale (non-unique titles mean duplicate retries create duplicates) and by disclosing the created object's state ('draft') and its returned id. It doesn't explain what makes the operation destructive (quota, irreversibility), which would be the remaining useful detail.

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

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

Two short sentences with zero filler. The core action and return value come first, and the retry caveat follows, so it is properly front-loaded.

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

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

Five parameters at full schema coverage, no nested objects, and no output schema — and the description supplies the one thing the missing output schema would have carried, namely that the response yields the id used by sibling tools. Nothing needed to call this correctly 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% with three enum-backed parameters fully documented, so the schema does the heavy lifting and a baseline 3 applies. The description only indirectly touches the `title` parameter (non-unique), adding no syntax or format detail beyond the schema.

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

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

States a specific verb and resource ('Create a draft game') and adds the crucial scope qualifier 'draft', which distinguishes it from publish/launch siblings. It also names the returned artifact ('Answers its `id`, which the other tools take'), telling the agent exactly how the result feeds downstream calls.

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: titles are not unique, so after an ambiguous failure check list_applications before retrying. That is a genuine when-to-use-alternative instruction. It doesn't cover prerequisites (e.g. account/submission state) or when the tool should simply not be called, so it falls short of a 5.

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

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

Annotations already declare this is a non-read-only, non-idempotent, destructive write; the description goes beyond them by disclosing that `id` is immutable after creation and that no delete path exists. It does not describe what happens on a duplicate tag or permission/error behavior, so it is useful but not complete.

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 purpose, then the two constraints that actually affect the call. No redundancy or 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 6-parameter create tool with full schema coverage and a rich enum-laden schema, the description covers purpose, the immutability constraint, the pre-check requirement, and the absence of a delete counterpart. No output schema exists, so return values need not be described.

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 parameter descriptions are already rich (enums, defaults, semantics), so the baseline is 3. The description still adds genuinely new information: `id` is not changeable later, which the schema does not state.

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

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

The first sentence gives a clear verb+resource ('Add a leaderboard to a game'), immediately distinguishing this from read/update siblings. It does not explicitly contrast with update_leaderboard, the closest sibling, so it falls short of a 5.

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

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

It routes the agent to a sibling with a condition: 'Check list_leaderboards for tags already taken,' and states a limitation the agent must plan around ('Deleting a leaderboard is not available'). It never states when to choose create vs update_leaderboard, so it stops short of explicit when/when-not 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, idempotentHint, and destructiveHint false, so safety behavior is covered. The description adds useful expectations about the response: it contains only metadata, not file contents or download links. This goes beyond annotations by clarifying payload scope, though error and authentication behavior are not mentioned.

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

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

The description is two short sentences with no filler. The first sentence states the resource and return scope; the second states an important exclusion. Everything included earns its place, and key constraints are front-loaded.

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

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

For a one-parameter read operation with strong annotations and no output schema, the description sufficiently conveys what result to expect and what it excludes. It could be more complete by naming alternatives or listing return fields, but the definition is usable as-is.

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

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

The single parameter applicationId is fully documented in the schema, including a source hint ('as returned by list_applications'), so schema coverage is 100%. The tool description itself adds no additional parameter detail. At this coverage level, the baseline of 3 is appropriate.

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

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

The description identifies the output as the saved form of one game and explicitly narrows scope to metadata of archives/media, distinguishing it from file/download tools. It lacks an explicit action verb like 'reads' or 'returns', but the title and 'saved form' make the read intent clear. It does not name siblings like list_applications, but the singular 'one game' is informative.

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 phrase 'one game' implies the tool is for retrieving a single existing application rather than listing or creating. 'No file contents or download links' is an explicit when-not condition. The description does not name an alternative tool, but the negative scope is strong enough to prevent misuse.

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 communicate readOnly/idempotent/non-destructive behavior. The description adds value beyond that by saying the answer also contains `processing`, `failedAt`, and `bridgeSdk`, that this tool 'unlocks nothing', and by explicitly warning the agent to take the link from the answer rather than build it. This is useful non-obvious behavior, though edge cases and response shape are not fully expanded.

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 core behavior, then covers the mode variant, related answer fields, and a critical do-not-build instruction. Every clause earns its place; there is no filler or 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?

With no output schema, the description compensates by naming returned fields and telling the agent where to find the link. It also states the key precondition (`processing` DONE) and the certification-mode context. It could be more complete about exact output structure or failure behavior, but for a read-only link retrieval it is largely sufficient.

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 schema already explains `mode`'s certification behavior plus the provenance of `applicationId` and `archiveId`. The main description reinforces the mode semantics but adds no new parameter-level meaning, so the baseline 3 applies.

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

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

The description makes the deliverable clear: a Playgama QA Tool link for an unpacked archive, with mode-specific behavior and related fields like `processing`, `failedAt`, and `bridgeSdk`. It is unambiguous about the object being an archive rather than a local game, though it never explicitly names a sibling such as `get_local_game_qa_tool_link`, so it stops short of full sibling differentiation.

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

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

It gives concrete conditional guidance: the default is the ordinary testing page, `mode: certification` is for the Build Startup/certification page when Bridge SDK initialization is the concern, and `get_bridge_sdk_docs` is pointed to for integration docs. It lacks an explicit 'do not use this for status' or 'do not use this for local game links' exclusion, so it is not 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 cover read-only/idempotent safety, yet the description goes well beyond them: it documents the full status state machine, the PENDING/DONE/FAILED processing lifecycle including `failedAt: UNPACK`, the bridgeSdk tri-state, null analysis fields, and the gating rule that publishing/submitting depend on `state` while sandbox traffic also requires `bridgeSdk` FOUND.

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

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

It is a single dense paragraph but front-loads the core fact ('The state of one archive') and every sentence carries field-level meaning or an actionable rule. It is long, though, and would read better segmented, which keeps it from 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?

With no output schema, the description carries the full burden of explaining return values, and it does so comprehensively: status values, processing states, bridgeSdk states, analysis fields, and how each maps to a developer action. Nothing an agent needs to interpret the response is missing.

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

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

Schema description coverage is 100% and both parameters are documented in the schema itself, so the baseline is 3. The description adds no additional meaning about archiveId or applicationId beyond what the schema already 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?

The description opens with a specific verb+resource: 'The state of one archive,' and immediately enumerates the meaning of `state.status`. The resource noun 'archive' separates it from get_sandbox_state and get_submission_state, though no sibling is named explicitly, which keeps it just short of a 5.

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

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

It gives concrete operational guidance: 'Poll until it is no longer CHECKING,' and routes the agent to get_bridge_sdk_docs and get_archive_qa_tool_link with a specific mode when status is PROBLEM. No explicit when-not-to-use statement is given, but the polling and remediation conditions are clear.

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

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

Annotations declare read-only/idempotent/no-destructive, and the description goes well beyond them: index shape when `page` is omitted, full page payload (title, url, markdown) when supplied, tab-cutting behavior via `engine`, `engineFilter` reporting, and refusal of unknown ids with valid list. This is rich behavior an agent could not infer from the annotations.

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

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

Front-loads purpose and then describes the two calling modes compactly, with every clause carrying information. Dense backtick notation and long compound sentences cost a point on readability but not on waste.

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

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

No output schema exists, and the description fully compensates by describing both return shapes (index entries with page/title/required/description, and page content with url/markdown/engineFilter). Nothing needed to call or interpret the tool is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics: the dual mode of `page` (index vs. page fetch) and the tab-filtering side effect of `engine` including what `engineFilter` reports. The schema still carries the enumeration/format details, so it is not a full 5.

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

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

States a specific verb and resource (read the live Playgama Bridge SDK wiki) plus the precise triggering conditions (archive answered `bridgeSdk: NOT_FOUND`, or traffic refused with `NO_BRIDGE`). An agent can distinguish this docs tool from the game-checklist sibling without opening either schema.

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

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

Gives an explicit when-to-use trigger (Bridge SDK integration after a NOT_FOUND / NO_BRIDGE result) and names the alternative, get_game_checklist, along with what that sibling covers. Routing between the two is left unambiguous.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description adds value by disclosing the response shape: a `howToChoose` rule plus `categories` entries carrying `value`, `label`, `description`, `like`/`examples`, and `notLike`. The 'same list the console shows the developer' note also reassures the agent it is the canonical source.

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

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

Front-loads the core purpose, then usage, then output structure. The field enumeration is dense but every clause carries meaning, and there is no filler. Slightly backtick-heavy but appropriate for the domain.

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

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

With no output schema, the description fully carries the burden of explaining return values, enumerating each returned field and its role, plus the selection rule. An agent has everything needed to call it and interpret the result without opening any other artifact.

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 description appropriately does not invent any. It does describe the semantics of the `category` field values it returns (priority order, how to choose, what `like`/`notLike` mean), which is useful context even though it is not an input.

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 resource (the `category` values that update_application_form accepts) and frames it precisely as a read of the categories in priority order with selection guidance. It is easy to distinguish from the writer tool it complements (update_application_form) and from other read tools in the sibling 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 a clear usage condition: 'Read it before setting or changing a game's category', which ties the tool to the mutation flow it supports. It stops short of an explicit exclusion (e.g. when not to call it, or what to do if you already know the value), so it does not reach the full when/when-not/alternative standard.

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-open-world status, but the description goes further: it discloses that content is read live from the wiki and precisely describes the return payload shape for both the no-`page` and `page` cases (`{ title, url, markdown, pages }` vs a single page's title/url/markdown). This is rich context with no contradiction.

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

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

The description is dense and slightly run-on, but front-loaded with purpose then workflow then return shape, and every sentence contributes useful information. Minor trimming of redundant phrasing would improve it.

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

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

For a single-parameter read tool with no output schema, the description is complete: it explains what the checklist is, when to consult it, what to do with the results, and the exact shape of both return variants. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the `page` parameter's id semantics and link-copying tolerance are already documented in the schema, setting a baseline of 3. The description adds value by explaining the output effect of omitting vs supplying `page` and how nested page ids relate to the checklist, pushing it above baseline.

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

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

States a specific verb and resource — reading the Playgama game checklist — and spells out exactly what the resource contains (Bridge steps, build requirements, tips). It is clearly distinguishable from siblings like get_bridge_sdk_docs, which it explicitly routes to for SDK links.

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

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

Gives explicit timing: read before integrating the Bridge SDK and before every start_archive_upload. It also prescribes the follow-up action (check each item, fix failures, report items it could not verify), leaving nothing to inference.

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

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

Annotations already declare the safe read-only/idempotent profile, but the description adds substantial context beyond them: the 31-day max span, the 50-default/100-capped inventory, cursor-following rules to avoid over-fetching, dynamic JSON with possible unknown fields, and the critical 'missing or null never means zero' semantics. It also flags the response as evidence rather than a conclusion, which is meaningful behavioral framing.

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 in the first sentence and every subsequent sentence carries a distinct constraint rather than filler. It is dense and slightly long, but no sentence is redundant, so it earns most of its length.

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

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

With no output schema, the description takes on the burden of describing returns and does so concretely (volume, inventory, sessions, users, duration, freshness, plus schema_version/period/sample sizes to inspect). Combined with the pagination and date-range rules, an agent has everything needed to call and interpret the tool correctly.

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

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

Schema coverage is 100%, establishing a baseline of 3, but the description adds real meaning: dateFrom/dateTo are inclusive calendar dates that may span at most 31 days (a constraint absent from the schema), and eventCursor should only be followed when more event types are needed for the current question. This is value beyond the schema, though eventLimit's stated bounds largely duplicate the schema.

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

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

The description states a specific verb and resource ('compact overview of one game's preaggregated telemetry') and immediately enumerates what it covers (volume, event inventory, sessions, users, duration, freshness). It explicitly distinguishes itself from the sibling telemetry tools by naming the event, timeseries and session-facts alternatives, so an agent can route 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 gives an explicit entry-point instruction ('Start here') and an explicit exclusion ('call the event, timeseries or session-facts tool only for the question you need to answer' / 'do not fetch every page preemptively'). It also names a prerequisite guide tool for interpretation, leaving nothing to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real behavior: the omit/pass fieldName dual mode, bounded categorical results with an other_event_count catch-all, and that nested structures come back as dynamic JSON rather than a fixed DTO. It does not say what happens for an unknown fieldName or invalid eventName, so it falls short of 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?

Five sentences, each carrying a distinct fact (mode 1, mode 2, data shape caveat, performance_sample special case, upstream source and exclusion). Front-loaded with the primary behavior and free of restatement of the name or annotations.

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

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

A read-only, non-destructive tool with no output schema and full parameter coverage; the description conveys both call modes, the result shape, and the upstream discovery path, which is enough to invoke it correctly. Minor gaps remain around failure/empty cases and how many categorical values 'bounded' means.

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 genuinely adds semantics beyond the schema: fieldName is optional and its presence/absence selects two different result shapes, and nested JSON stays inside that field's value. It adds nothing further about eventKind/applicationId beyond what the schema text already 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 resource and scope ('Preaggregated detail for one event') and then says exactly what the tool returns in each mode: field inventory with type/coverage/cardinality/summary, or bounded top categorical values plus other_event_count. An agent can distinguish this from the sibling telemetry tools (session_facts, timeseries, analytics) without opening the schema.

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

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

Explicit two-step workflow ('Call without fieldName... Call again with one fieldName'), an explicit upstream dependency ('Use event names discovered in get_game_telemetry_analytics'), an explicit exclusion ('do not request raw events'), and a named special case (performance_sample FPS/frame-time/stutter). Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real content disclosure: it names the performance_sample contract, bounded progression events, the custom-to-system event migration, and privacy rules — telling the agent what to expect inside the guide rather than just that it is safe to 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?

The load-bearing instruction ('Read before finishing a game') sits early, and every listed item maps to a distinct concern. It is a single dense sentence with a long enumerated tail, so it loses a little on scannability but wastes no words.

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 guide with no output schema, the description is nearly complete: it covers the trigger condition, the topics contained, and the intended drill-down workflow. A brief note on what is returned (documentation text vs. structured data) would close the last 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 tool takes zero parameters, which is the baseline-4 case; there is nothing in the description that could or should add parameter meaning. Schema coverage is trivially 100%.

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 resource and audience: 'Agent-only instructions for instrumenting a Playgama game and interpreting its telemetry.' It immediately distinguishes itself from the sibling analytics tools by positioning itself as the guide that explains how to use them ('how to drill down through the compact telemetry analytics 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?

Gives an explicit trigger ('Read before finishing a game') and an explicit anti-pattern ('without requesting raw or unnecessarily large datasets'), plus it tells the agent when to consult the analytics siblings. No named alternative is excluded outright, but the routing intent 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds substantive traits: preaggregated and pseudonymized data, dynamic sanitized JSON in ordered chunks, deliberate exclusion of repetitive event types, and the caveat that facts are not a complete user history. None of that is derivable from the annotations or 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?

Five tightly packed sentences, front-loaded with the resource and its purpose, then constraints, then exclusions. Every sentence carries a distinct, actionable fact; nothing is restated from the schema or 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 still characterizes the return payload (sanitized JSON in ordered chunks, paginated, cursor-driven) and warns about its limits as a history source. Combined with the missing-parameter constraint and exclusions, an agent has everything needed to call it correctly and interpret results.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds a genuine cross-parameter constraint absent from the schema: at least one of eventName, fieldName, sessionRef or userRef must be supplied (the schema only marks applicationId/dateFrom/dateTo as required). It also sets the paging expectation ('default 20-session page'), which only partially duplicates the schema's limit default.

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?

Names a specific resource ('paginated, preaggregated and pseudonymized session facts') and a concrete query class (sequence questions like item-before-death or restart-after-defeat). It implicitly separates itself from the raw-event sibling by stating 'they are not raw events', so an agent can distinguish it from get_game_telemetry_analytics/timeseries 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?

Gives clear when-to-use (sequence questions), explicit when-not ('never filter session facts by core_ping or performance_sample', 'not for per-session FPS analysis'), and a pagination policy. It stops short of naming the sibling tool to use instead for those excluded cases, so the alternative is implied rather than stated.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds substantial behavioral context: pagination via page.next_cursor, the response returning the applied limit, what the points do and do not represent (volume/coverage, not FPS or custom-field distributions), and that raw events are never read or returned.

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

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

Front-loaded with the core purpose and scope, then caveats. Six sentences is on the longer side, but each adds a distinct constraint (grain, narrowing, pagination discipline, semantic scope, routing, raw-event exclusion).

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

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

No output schema exists, yet the description explains what the response contains (points, next_cursor, applied limit), and covers grain, filtering, and boundaries. An agent has everything needed to call and interpret 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 schema already documents all 8 params and 3 is the baseline. The description adds meaning beyond the schema by clarifying the granularity options (30-minute vs daily), the event namespace/name narrowing, and the limit/cursor relationship to pagination.

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: preaggregated 30-minute or daily telemetry counts. It differentiates from siblings by scoping to volume/coverage trends and explicitly pointing performance-value comparison to event-analytics requests.

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 clear context (trend, release, regression comparisons) and narrowing options, plus a pagination-following rule and a routing hint away from performance queries. The alternative is described generically as 'bounded event-analytics requests' rather than naming the specific sibling tool, so routing is slightly less than explicit.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, yet the description adds substantial behavior beyond them: the full state enum, the semantics of 'current' and of UNKNOWN ('call again'), the meaning of CABINET, and the special traffic-step resolution and bonusId reuse rules. These are meaningful operational details not derivable from structured fields, though return-value formatting is left implicit.

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

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

It is front-loaded with the core definition (ordered path, judged by latest archive) before the field list and edge cases. The traffic paragraph is dense and long relative to the rest, but each clause carries real semantic weight, so it remains reasonably economical.

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?

This is a complex state-machine tool with no output schema, and the description compensates well: it enumerates the step fields, explains `current`, resolves the UNKNOWN and CABINET cases, and details the traffic step's two paths. Enough is present to interpret the result, with only minor gaps in describing overall response shape.

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

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

Only one parameter (applicationId) and schema description coverage is 100%, so the schema already documents it fully. The description references the archive (archiveId) and bonusId, but bonusId is a return field, not a parameter, so it adds little parameter-level meaning. Baseline 3 is appropriate.

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

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

The description states a concrete verb+resource: it returns 'the developer's path for the game, in order' with an explicit ordered list of steps (archive, bridge, covers, form, sandbox, share, traffic). That is clear and specific. It does not, however, name or differentiate itself from plausible siblings like get_submission_state, get_game_checklist, or get_sandbox_state, so it stops short of a 5.

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

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

It gives one conditional usage rule — 'UNKNOWN is neither done nor not done: call again' — and explains how the traffic step resolves (prefer an available referral bonus, else SHARE needs public links). But it never says when to call this versus the many sibling status tools (get_submission_state, get_game_checklist, get_sandbox_state), so the when-to-use guidance is only implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavior beyond those: sessionId omission creates a fresh environment, reusing it preserves state, and the agent must take the link from the answer rather than constructing it.

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, each earning its place: what the link is for, how sessionId changes behavior, and a caution not to build the link manually. The core purpose is front-loaded.

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

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

For a simple 2-parameter read-only tool, the description fully covers purpose, parameter semantics, and expected output behavior ('Take the link from the answer'). No output schema exists, but the description compensates by telling the agent exactly what to extract.

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 100% of parameters, so the baseline is 3. The description adds meaning beyond the schema by explaining the behavioral difference between omitting and reusing sessionId, which is not captured in the parameter's 'Default: current timestamp' text.

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

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

The description states a specific deliverable ('a link that opens the Playgama QA Tool'), a clear target ('a game you serve yourself, e.g. on localhost'), and a clear use case ('before uploading'). This distinguishes it from the sibling get_archive_qa_tool_link, which would target archived games.

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

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

The description clearly indicates when to use the tool: for locally served games being tested in the Bridge SDK harness before upload. It does not explicitly name the alternative for already-uploaded or archived games, so it lacks an explicit exclusion.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior, but the description adds substantial semantics beyond them: return fields, status transitions, retryAfterSeconds, and the meaning of an absent destination. It also warns that a publish_sandbox with no answer may still land later and explains how to detect that outcome. There is no contradiction with the annotations.

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

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

The purpose is front-loaded and much of the detail is justified because there is no output schema. However, the prose is extremely dense, with nested em-dash clauses and a final sentence that is difficult to parse. Some context, such as publisher ownership details, could be trimmed or separated without losing essential guidance.

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

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

With no output schema, the description must carry the return-value burden, and it does: it explains publication fields, statuses, retry behavior, ordering, and caveats about absent destinations. It also connects the result to related tools and post-publish verification. Given the annotations and complete schema coverage, the definition is contextually 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?

The input schema has 100% description coverage for the single applicationId parameter. The description does not mention applicationId or add any syntax or format detail beyond the schema. With the schema doing all parameter work, the baseline score of 3 is appropriate.

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

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

The first sentence identifies the resource and scope: latest publication per destination, newest first. It also distinguishes the tool from siblings like get_application activeArchives and get_sandbox_state. However, it states the content as a noun phrase rather than with a clear verb, and relies on the jargon term 'destination' without immediate definition.

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 routes the agent to get_application activeArchives for what a destination serves and to get_sandbox_state site.revision for the sandbox's current state. It also explains how to compare a PLAYGAMA_SANDBOX publication before and after publish_sandbox. A crisp 'use this when' statement is still absent, leaving the core invocation context implied rather than stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral context: the bonus grant lifecycle (invited org gets a welcome bonus; inviter gets another on first successful Sandbox publication), that bonuses are traffic not cash, and that merely reading or applying a code does not start traffic.

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 sentence, with mechanics following. Nearly every sentence adds decision-relevant detail, though the bonus-application walkthrough is somewhat long relative to a no-parameter read 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?

With no output schema available, the description carries the burden of describing returns and does so (invitation.url, counts, bonuses), plus eligibility rules and the downstream start_sandbox_traffic workflow. An agent has everything needed to call it and act on 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?

The tool takes zero parameters, so there is no parameter surface to document; baseline is 4. The description instead describes an output field (invitation.url) and the bonusId consumed by a sibling tool, which is useful but not parameter semantics per se.

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

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

The opening sentence names a specific verb (Read) and enumerates the exact resource contents: stable invitation code/link, eligibility, aggregate invitation counts, and available traffic bonuses. It is clearly distinguishable from the sibling apply_referral_code, which mutates 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 states the tool is read-only sharing ('share the returned invitation.url'), explicitly notes there is no enrollment step, and routes the agent to alternatives: read get_sandbox_traffic, then call start_sandbox_traffic with bonusId instead of postUrls. The eligibility boundary (accept until first-ever Sandbox publication) tells the agent when the program still 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context: `share` is null when unpublished/blocked, and the warning 'never build them' is a critical constraint that an agent could not infer from annotations alone.

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

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

Two sentences deliver the core content first, then add null behavior and a critical handling instruction. No filler or repetition. Slightly dense with backticks and terms, but every clause earns its place.

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

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

For a simple one-parameter read tool with no output schema, the description adequately covers what is returned (`share.text`, `share.links`, null case) and how to treat the links. It is complete enough for correct invocation and basic handling without needing a full response schema.

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

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

Schema description coverage is 100%: the only parameter, applicationId, is already described as 'Application (game) id, as returned by list_applications'. The description adds no new parameter-specific detail, 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?

The description clearly states the specific resource ('the ready post (`share.text`) and share links (`share.links`)') and the action ('get'), making it distinct from sibling tools like get_sandbox_state or get_sandbox_traffic. The title 'Read the sandbox share post' reinforces the exact purpose.

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

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

No explicit guidance is given on when to use this tool versus alternatives. It implies usage for retrieving share content, but it does not mention when to prefer it over get_sandbox_state or how to handle the null case in terms of next steps. The Facebook-specific context is useful but does not clarify tool selection.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds real behavioral context: null when never published, BLOCKED masking, revision semantics, and changeStatus values (CHANGED/UNCHANGED/UNKNOWN) with the note that none of them refuse. It does not describe pagination or error behavior, keeping it short of 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?

It is a single run-on sentence stitched together with em-dashes and parentheticals, so the most important fact (what is returned) is not front-loaded and parsing takes effort. It is not bloated with filler, but the structure is poor for an agent scanning for the key behavior.

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 does the heavy lifting by enumerating the returned fields and edge cases (null, BLOCKED, revision, publish refusal, changeStatus), which is close to sufficient for a two-parameter read tool. The only gap is the unstated default when `archiveId` is omitted beyond the implied `site`-only response.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond the schema by spelling out what `archiveId` unlocks — the `publish` block (`allowed`, `reason`, `message`, refusal fields), `changeStatus`, and `archiveChanged`. This gives the agent meaning the raw schema field text does not 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 states the resource (the game's sandbox page), its live state (`site.revision`), and what the optional `archiveId` adds, so an agent can tell it apart from get_publications and publish_sandbox. However, the core verb is implicit — it never plainly says 'reads' or 'returns' the sandbox state at the start, relying on the title, and the answer is buried in a dense dash-clause.

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 routes the agent elsewhere for one case ('how a publish request went is get_publications') and notes the refusal text matches publish_sandbox, but it never states explicitly when to call this tool versus get_submission_state or get_publications. Usage is implied rather than prescribed.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description goes well beyond them: it explains that a referral bonus is independent of share limits but shares active-campaign capacity, enumerates verdict.reason states with remediation (publish first, upload covers, ask again shortly), and describes the PENDING→RUNNING polling lifecycle. This is substantive behavioral context an agent cannot 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 purpose and the key non-mutation boundary before the dense field/enum detail. The middle is a long run-on covering many fields, but given there is no output schema each clause carries information, so it is verbose without being 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?

With no output schema, the description carries the full burden of explaining return values, and it does: verdict/offer/referralOffer semantics, remainingFreeRuns, durationDays, budgetUsd accounting caution, and current/runs shapes with status and failureReason. Nothing essential for correct interpretation 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?

Single applicationId parameter with 100% schema description coverage ('as returned by list_applications'), so the schema carries the semantics. The description adds nothing about the parameter itself, making the baseline 3 appropriate.

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

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

States a specific verb (Read) and resource (campaign eligibility, bonus offers, existing traffic runs for this game), and explicitly bounds scope with 'This read does not launch a campaign or spend a traffic bonus,' cleanly separating it from start_sandbox_traffic. An agent can distinguish it from get_sandbox_share and get_sandbox_state from the text alone.

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

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

Clear context for the read and routes the agent to get_bridge_sdk_docs when NO_BRIDGE is returned, and tells the agent to poll runs after a start. It does not explicitly name when to prefer get_sandbox_share or get_sandbox_state over this tool, so the sibling boundary is implied rather than stated.

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

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

Annotations only cover the safety profile (readOnly/idempotent/non-destructive), so the description carries the behavioral load and does so richly: ordered reason codes, the hard invariant that while catalogAvailable is false the answer is always MODERATION_UNAVAILABLE and the developer must never be told the game is submittable, the 100-plays/5-minute/day-counted unlock rule, and the Playgama-only reopen condition. This is well beyond what the annotations provide.

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

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

The purpose is front-loaded, and given the absent output schema much of the reason-code content is necessary. However, it is delivered as one dense paragraph with nested parentheticals, making the enumerated reason codes hard to scan; a structured list would convey the same information with less parsing effort.

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 must define the response shape, and it does: it accounts for reason, message, archiveId, catalogAvailable, emptySlots and details, and explains the ordering semantics of reason. Combined with the state-machine rules, an agent has everything needed to call and interpret this 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 genuine meaning on top by characterizing archiveId as 'the build you are asking about — the one a submit would freeze' and restating reviewType's AUTO/MANUAL split in terms of which downstream operation is being judged. It does not add syntax or constraint detail beyond the schema, but the conceptual framing is useful.

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

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

The opening states a precise predicate ('Whether the game can be submitted to moderation now and, if not, why') and frames the return as the first refusal rule a submit would hit. It explicitly names siblings it is not — get_archive_status ('explains it'), get_sandbox_state, and send_playgama_catalog_update — so the agent can separate this read-only verdict tool from its neighbors 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 strong conditions: MANUAL judges a console-submitted moderation request, AUTO judges send_playgama_catalog_update, and it notes that a human (not this tool) performs the actual submit. It names the alternative tools for adjacent questions, but never states an explicit 'do not call this for X' exclusion, so it falls just short of the 5 bar.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description adds that untitled and deleted games are excluded and that ordering is stable for paging. These are useful behavioral details not derivable from annotations or 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?

Three concise sentences with zero fluff: purpose and fields first, then ordering stability and exclusions, then the no-filters note. Every sentence earns its place.

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

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

For a simple list tool with two optional parameters, no output schema, and safety annotations already covering read-only/idempotent behavior, the description fully covers purpose, returned fields, ordering, exclusions, paging behavior, and filtering limitations.

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 skip and limit are fully documented there. The description adds only the paging stability hint, which is behavioral rather than parameter-specific; it does not enrich the meaning of the parameters themselves.

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 (list) plus resource (named games) with the exact fields returned and ordering ('newest first'), clearly distinguishing from the singular sibling get_application and other list tools like list_leaderboards.

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 there are no filters and instructs the agent to match on title or status itself, implying this tool is for unfiltered, paginated listing. It doesn't name an alternative tool directly, but the context is clear enough for an agent to decide when to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description doesn't need to repeat those. It adds valuable behavioral context by explaining that the output includes a checksum and that this checksum is intended for use with replace_in_app_products, which goes beyond the annotation 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 two sentences with no redundancy. The first sentence states the core functionality, and the second provides a critical usage hint about the checksum. It is efficiently front-loaded and every word 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?

For a simple list tool with one parameter and no output schema, the description gives enough to understand the result (catalog and checksum) and how the result integrates with a sibling tool. It could specify the structure of the catalog, but for the intended workflow this is sufficient.

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 parameter applicationId already has a clear description referencing list_applications. The tool description adds no additional parameter-level detail, so it relies on the schema, which is sufficient. Baseline of 3 is appropriate.

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

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

The description states the tool returns the saved in-app catalog and its checksum, which clearly implies a listing operation. It differentiates from the sibling replace_in_app_products by explicitly mentioning the checksum flow. However, the description doesn't use the verb 'list' itself, relying on the title for that.

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 a clear hint that the checksum should be passed to replace_in_app_products, indicating a common use case. It does not explicitly state when to use this tool vs alternatives, nor does it mention any exclusions or prerequisites beyond the schema's applicationId reference to list_applications.

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 the operation as read-only, idempotent, and non-destructive. The description adds useful context about response rows, the read-only nature of score-protection settings, and the semantic meaning of `id`, without contradicting 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 short and dense, front-loading the purpose and packing field semantics into one sentence. The opening fragment 'The leaderboards of a game' is slightly awkward but not 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?

For a single-parameter, read-only list tool, the description covers the output fields and the cross-tool id relationship, and the schema covers the input. It does not explicitly state the return container or pagination, but the 'rows' wording implies a list and nothing critical 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 only parameter, applicationId, is fully described in the schema as 'Application (game) id, as returned by list_applications.' The description does not elaborate on this parameter; its `id` explanation refers to a row field, not the input. Baseline 3 applies because schema coverage is 100%.

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 'List leaderboards' supplies a specific verb, and the description defines the resource as 'the leaderboards of a game.' It also clarifies that `id` is the SDK tag and the identifier consumed by update_leaderboard, which distinguishes this read tool from its update sibling.

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 implies a workflow—listing leaderboards gives you the `id` needed for update_leaderboard—but it never explicitly states when to choose this tool over create_leaderboard or update_leaderboard. There are no prerequisites or exclusions, only minimal 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 establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context beyond annotations: 'newest first' and 'grouped by moderation task.' It also reinforces read-only, consistent with annotations. No contradiction, and no critical behavior (e.g., authentication, pagination) is disclosed, but the added ordering/grouping is valuable.

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 front-loaded sentence that captures purpose, ordering, grouping, and read-only nature without redundant words. It earns its place for a simple read 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 one-parameter, read-only tool with strong annotations, the description is sufficient. It specifies scope ('on a game') and output organization ('newest first, grouped by moderation task'). No output schema exists, but the description gives enough context for a correct call. Minor omission: it doesn't describe the returned data structure, but that is acceptable given simplicity.

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

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

Schema description coverage is 100%; the only parameter, applicationId, is already documented as 'Application (game) id, as returned by list_applications.' The tool description adds no parameter-level detail beyond mentioning 'on a game.' Baseline 3 applies because the schema fully covers the 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?

The title 'Read the moderation correspondence' and description 'The moderation correspondence on a game, newest first, grouped by moderation task. Read-only.' clearly identify a specific verb (read/list), resource (moderation correspondence on a game), and key behaviors. No sibling tool appears to handle moderation correspondence, so it is easily distinguished.

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 implies usage (when you need to view moderation correspondence for a game) but does not explicitly state when to use it or when not to, nor does it name alternatives. Since there are no sibling moderation tools, ambiguity is low, but explicit guidance is absent.

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

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

Annotations already declare destructive=true, idempotent=false, openWorld=true, but the description adds far more: exact prerequisites (build check PASSED, Bridge 2.2.0+, three covers, complete form), the async PENDING outcome with url/revision semantics, the 409 on concurrent publish, and a rate limit of 15 publications per rolling hour with quota resetsAt 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 critical facts are front-loaded: what it does, the public/no-moderation nature, and 'Ask the developer first' lead the text. It is dense and reads as a single long paragraph, but the length is earned by the large refusal-code surface and the async publication flow rather than filler.

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

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

With no output schema and a genuinely complex asynchronous mutation, the description carries the full burden and delivers: it documents the return shape (outcome, url, revision), the polling protocol, every refusal reason and its remediation, and the preconditions.

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 updateNote/archiveId are already exhaustively documented in the schema, so the baseline is 3. The description reinforces the archiveId prerequisites and updateNote timing but adds little that the schema does not already 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?

States a specific verb (publish) and resource (this archive to the game's sandbox) and immediately qualifies the target as 'a public page anyone with the link can play, without moderation.' This distinguishes it clearly from read-side siblings like get_sandbox_state and get_publications.

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 to ask the developer first, to read get_sandbox_state with the same archiveId beforehand, and to follow get_publications afterward. It names when-not conditions (PUBLISHED_ON_PLAYGAMA, BLOCKED) and routes to get_archive_status and get_bridge_sdk_docs for prerequisites, leaving nothing to inference.

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

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

Goes well beyond the destructiveHint annotation by spelling out the concrete consequences: omitted products are deleted, an empty list clears the catalog, and there are two refusal modes (checksum mismatch and IN_GAME_PURCHASES_OFF). This is exactly the operational detail 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?

Front-loads the replacement semantics, then consequences (deletion, clearing), then prerequisites and refusal conditions. Three dense sentences with no filler; every clause carries actionable information.

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

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

For a destructive four-parameter tool with no output schema, the description covers scope, side effects, prerequisites, and failure modes completely. Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so the schema already documents each field; the description's added value is tying expectedChecksum to the list_in_app_products output and explaining the refusal on mismatch. It reinforces rather than adds new per-parameter syntax, so slightly above baseline.

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

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

States a specific verb (replace) and resource (the whole in-app catalog), and immediately distinguishes itself from list_in_app_products by emphasizing it is a full replacement, not a patch. An agent can identify the operation without opening the schema.

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

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

Explicitly names the prerequisite (read list_in_app_products first and pass its checksum), the safety action (ask the developer before removing products), and the alternative path when purchases are off. Names the relevant sibling tool directly.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and idempotentHint=false, and the description adds substantial non-obvious behavior: no moderation before going live to every player, the PENDING/outcome and releaseId return, the PUBLISHED/FAILED terminal states, 409 PUBLICATION_IN_PROGRESS, retryAfterSeconds pacing, the unreliability of a no-answer call, and named refusal reasons with instructions to relay messages verbatim.

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 is front-loaded, but the body is a dense wall of semicolon-chained clauses, bolded fragments and mid-sentence imperatives that an agent must parse carefully. Nearly every statement carries operational value, so it is not padding, yet the presentation is far from tight and could be restructured 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?

For a destructive, non-idempotent publish call with no output schema, the description covers the full lifecycle an agent needs: pre-call reads, acceptance criteria, asynchronous outcome, follow-up polling, terminal states, refusal handling, and retry-on-new-yes semantics. Nothing needed to invoke it correctly appears to be missing.

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

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

Schema description coverage is 100% and the updateNote schema description is itself extremely detailed, so the schema already carries most parameter meaning. The description reinforces the 'write updateNote every time' requirement and the archive/form coupling, but adds little semantic detail beyond what the schema already states, so the baseline 3 applies.

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

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

The opening states a specific verb and resource: send an archive plus saved form to the Playgama catalog as an update of the live game. It immediately distinguishes itself from first publication and from the sandbox/second platform paths that go to moderation, so the agent can place it among siblings like publish_sandbox and update_application_form.

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 gating conditions are given: call only on the developer's explicit yes in this conversation, and a yes to an earlier update or a sandbox publish does not count; read get_submission_state with AUTO and get_publications before calling; only a game live in the catalog with autoReviewPlatforms PLAYGAMA qualifies. Alternatives (first publication, other platforms) are named and routed elsewhere.

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

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

Beyond the destructive/non-idempotent annotations, the description discloses the critical hidden contract: the URL is returned in `uploadUrl`/`headers`, must be PUT to with exactly those headers, and expires in one hour. That signing/expiry behavior is exactly the kind of context annotations cannot carry.

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

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

Front-loads the step number and the checkout gate, then the return values and the curl example. Dense but purposeful; the inline example slightly lengthens it but earns its place by pinning the exact invocation.

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

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

Even with no output schema, the description names the returned fields and the follow-up call, and states the expiry window. For a multi-step mutation tool this is complete enough to invoke correctly on the first try.

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 schema itself explains name, contentSize (signed-length constraint) and applicationId in detail, so the baseline is 3. The description adds only the implicit tie between the zip and contentSize via the checklist/game.zip flow, not new parameter semantics.

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 ('start an archive upload') and frames it as 'Step 1 of 3 of uploading a build', which immediately distinguishes it from confirm_archive_upload and start_cover_upload. An agent knows exactly what this tool initiates.

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 prerequisite ('read get_game_checklist and check the build against each item first') and an explicit successor ('then call confirm_archive_upload'), plus the deadline ('within an hour'). The when-to-use path is fully prescribed 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?

Beyond the destructiveHint/readOnlyHint annotations, the description discloses that the response contains uploadUrl and headers, that the PUT must happen within an hour with exactly those headers, and that confirmation is a separate later step. It does not spell out that confirmation replaces an existing cover, but the schema covers that and the annotation already flags destructiveness.

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

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

Two sentences deliver the purpose, output, time constraint, and next step with no filler. The workflow is front-loaded.

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

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

For a stateful first-step upload tool, the description gives the response shape, the required action, the validity window, and the follow-up call. With the rich parameter schema and annotations, nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already explains all four parameters in detail. The description adds a useful curl example but does not materially expand on parameter semantics beyond the schema.

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

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

The description states a specific verb and resource ('Step 1 of 3 of uploading one cover') and explains what the tool returns (uploadUrl and headers). It clearly distinguishes itself from confirm_cover_upload by naming it as the next step and from archive uploads by the word 'cover'.

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

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

It explicitly positions the tool as the first step in a three-step cover-upload flow and instructs the caller to PUT the file then call confirm_cover_upload. It does not explicitly exclude start_archive_upload, but the 'cover' resource makes the intended context 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?

With annotations only telling the agent this is a non-readonly, non-idempotent, open-world, destructive write, the description discloses the behaviors that actually matter: budget/reservation semantics on uncertain outcomes, the rule that a timeout is not permission to spend another bonus, retryability limited to confirmed safe failures, PENDING-run polling and requeue, and the specific refusal codes (SHARE_REQUIRED, INVALID_POST_URL, PAYMENT_REQUIRED). This is rich context well beyond structured fields.

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

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

The critical guidance (one of bonusId/postUrls, reuse after uncertainty) is front-loaded, but the body is a dense wall of run-on sentences with several rules repeated between description and schema (postUrls credits, retry semantics). It is information-dense yet oversized and hard to scan, so it is not appropriately concise even though most sentences carry real meaning.

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

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

For a destructive mutation tool with no output schema, the description covers everything an agent needs: inputs, prerequisites, failure modes, retry/idempotency-safe behavior, error codes, and the polling follow-up via get_sandbox_traffic. 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 the schema already documents all three parameters and the 3-unit cap. The description adds operational meaning to those parameters: reusing the same bonusId/applicationId after an uncertain answer, the 1–3 link range with one boost unit each, and that later link additions extend the same campaign rather than create a new one.

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 precise verb and resource (start an ad campaign that sends players to the sandbox page), which is immediately distinguishable from siblings like get_sandbox_traffic (polling) and get_sandbox_share (posting). An agent can tell what this tool does without opening the schema.

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

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

Explicitly routes between the two input modes ('Send exactly one of bonusId or postUrls'), names the source tools for bonusId (get_referral_program, get_sandbox_traffic) and for share links (get_sandbox_share), and states the exclusion that a referral bonus needs no social post. Prerequisite ('ask the developer first', needs covers in published revision and Bridge SDK) is also given.

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 destructiveHint=true and idempotentHint=false; the description adds the non-obvious mechanics behind that — omission preserves the prior value, enum arrays are replaced wholesale, and nothing is sent for moderation. That is real added context an agent could not derive from the annotations. It still says nothing about permissions, error behavior, or what the call returns.

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, then the partial-save rule, then the moderation boundary. Every sentence carries information; no filler or restatement of the title.

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

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

For a 20-parameter, high-stakes save tool with no output schema, the description supplies the two things an agent most needs before calling: omission semantics and the fact that this is not a submission. Annotations cover the safety profile and the schema covers each field, so remaining gaps (auth requirements, response shape, failure handling) are minor.

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

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

Schema coverage is 100% and every one of the 20 parameters carries a rich inline description (enums enumerated, length limits, conditional submission rules). The tool description adds no parameter-level detail of its own, so the baseline of 3 applies — 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 description gives a specific verb and resource ('Save form fields of a game') and immediately scopes it against the submission flow ('Does not submit anything to moderation'). It is clearly distinct from create_application and get_application in intent, though it does not name a sibling explicitly.

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 operating mode ('Partial save: a field you leave out keeps its value') and a scope boundary ('Does not submit anything to moderation'), which tells an agent this is a draft-persistence call rather than a publish/submit step. No alternative tool is named for the read or submit case, so it stops short of full routing guidance.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false; on top of that the description discloses that at least one field must change, that the tag is immutable, and that no delete path exists. That is useful scope information beyond the annotation flags, though it says nothing about permissions or response 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?

Two compact clauses, front-loading the mutable fields and the at-least-one requirement before the negative constraints. No wasted wording.

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 5-parameter mutation tool with no output schema, the description covers the mutable surface and key limits. It could state whether changes are reversible or require specific permissions, but the essentials an agent needs to call it correctly are present.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a constraint absent from the schema: at least one of name/type/scoreOrder must be supplied, and it clarifies the tag (leaderboardId) is immutable. This meaningfully extends the parameter understanding.

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 (change/update), the resource (leaderboard), and exactly which fields are mutable (name, type, scoreOrder). It is immediately distinguishable from create_leaderboard and list_leaderboards by naming what is editable rather than created or listed.

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?

Adds decision-relevant constraints: at least one mutable field is required, the tag cannot change, and deletion is unavailable. It doesn't explicitly name an alternative tool for deletion, but the exclusions clearly scope when this tool applies.

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