Playgama MCP - Publish & Manage HTML5 Games

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

The description discloses many behavioral traits: one inviter per organization, irreversibility, self-invitation refusal, the $3 bonus, retry behavior, and state recovery. However, it directly contradicts the annotation idempotentHint=false by stating that repeating the same invitation returns ALREADY_APPLIED and the same bonus, even after a lost answer. This is an annotation 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 but every sentence and clause earns its place: invocation timing, prohibition on invented codes, invariants, bonus effect, retry semantics, and recovery path. It is front-loaded with the primary action and constraint, with no filler or repetition of schema content.

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

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

For a single-parameter tool with no output schema, the description is unusually complete: it covers when to call, constraints, side effects, repeated-call behavior, and how to recover state. The only flaw is the metadata contradiction, which is already penalized in behavioral transparency; the prose itself gives an agent everything needed to invoke the tool correctly.

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

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

Schema coverage is 100%, so the schema already fully documents codeOrUrl. The description reinforces that it is the code or full invitation URL supplied by the developer and adds the condition to use it before first publication, but it does not add significant semantic detail beyond the schema.

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

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

The description uses a specific verb and resource: 'Apply a developer-provided referral code or invitation URL to this organization' before the first Sandbox publication. It clearly separates this from get_referral_program by positioning that tool as the state-recovery alternative.

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

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

It explicitly states when to use the tool ('before its first-ever Sandbox publication'), what not to do ('Never invent a code'), who is refused ('self-invitations'), and how to disambiguate from the sibling get_referral_program after an uncertain result. This is strong guidance with both inclusion and exclusion criteria.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is known. The description adds valuable behavioral context: it is idempotent ('Safe to repeat'), it preserves earlier archives ('earlier archives stay'), it queues background work, and it returns 409 when no upload is pending. This goes beyond the annotations and helps the agent understand side effects and failure modes.

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

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

The description is compact and information-dense. Every sentence earns its place: the step context, the action, the failure mode, the idempotency, and the follow-up tool. It is front-loaded with the most important context ('Step 3 of 3, after the PUT') and contains no filler.

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

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

For a two-parameter tool with a fully documented schema and annotations covering the safety profile, the description is complete. It explains the workflow position, the side effects, the error condition, the retry safety, and the next step (poll get_archive_status). No output schema exists, but the description appropriately routes the agent to the status tool for 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 schema already documents both parameters (archiveId and applicationId) with their sources. The description does not add parameter-level detail beyond the schema, but it does reference the workflow context ('as answered by start_archive_upload', 'as returned by list_applications') in the schema. Baseline 3 is appropriate since the schema carries the 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?

The description clearly states the tool's role as 'Step 3 of 3, after the PUT' and specifies the action: 'adds the archive to the game's form' and 'queues unpacking and the Bridge SDK analysis'. This distinguishes it from sibling tools like start_archive_upload and get_archive_status, and the step context makes its purpose unambiguous.

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

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

The description explicitly says when to use it ('Step 3 of 3, after the PUT'), what happens if used prematurely ('Refused with 409 while nothing is uploaded'), and that it is safe to repeat. It also directs the agent to poll get_archive_status for the result, providing clear guidance on the workflow and alternatives.

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

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

Beyond the annotations, the description discloses that the tool validates the file, publishes it, places it into the slot, and names the replaced cover via `replaced`. It also explains the 409/422/502 failure modes, which is substantial behavioral context that annotations do not provide.

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

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

The description is dense but well organized: workflow position, validation steps, side effects, error codes, and retry safety are all covered in three sentences without filler. Information is front-loaded and each 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?

Despite no output schema, the description mentions the `replaced` result field and covers validation, publishing, side effects, error conditions, and retry safety. For a 2-parameter tool in a multi-step workflow, this is complete enough for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, and the parameter descriptions already explain that mediaId comes from start_cover_upload and applicationId from list_applications. The description adds no further parameter-level detail, so the baseline score of 3 is appropriate.

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

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

The description states a specific action (confirm a cover upload), identifies it as step 3 of 3 after the PUT, and explains what it does: validate, publish, and place the file into its slot. This clearly distinguishes it from sibling tools like start_cover_upload and confirm_archive_upload.

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

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

The description explicitly says when to call it ('Step 3 of 3, after the PUT') and gives actionable error-based guidance: on 422 start a new upload, on 502 it was not confirmed and can be retried. It also notes it is safe to repeat, making retry behavior 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 destructiveHint=true, idempotentHint=false, readOnlyHint=false, and openWorldHint=false, so the bar is lower. The description adds meaningful context beyond them: the created entity starts as a draft, its id is the key other tools consume, and titles are non-unique so retries can duplicate — directly relevant to the non-idempotent, destructive profile.

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 tight sentences, front-loaded with the core action and the return-value contract. The retry caveat is useful but slightly secondary; still, no sentence is wasted.

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

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

Covers the action, the draft state, the id contract for downstream tools, and the duplicate-title hazard. With no output schema, one might want a word on what 'draft' means for later publish steps, but for a 4-param, 2-required tool the essentials 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 description coverage is 100%, with rich enum descriptions for agent, model, and engine already in the schema. The description adds no parameter-level detail (e.g., which fields are required, engine/title constraints) beyond what the schema documents, so baseline 3 is appropriate.

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

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

States a specific verb+resource ('Create a draft game') and immediately clarifies the return value ('Answers its `id`, which the other tools take'), distinguishing it from sibling read/update tools like get_application and update_application_form. The draft-vs-published distinction adds useful scope.

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

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

Gives explicit caveat about non-unique titles and tells the agent to check list_applications before retrying after ambiguous failures, which is genuine when-to-use guidance. It does not name an alternative tool for the create path (there is none), so it stops short of the fullest 'use X instead' phrasing.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the description's warning about no deletion adds context beyond the annotations. It also discloses that `id` is immutable ('not changeable later'), which is a behavioral constraint not present in the schema. Minor gap: it doesn't state whether creation is idempotent or what happens on duplicate tag, but the annotation covers idempotency.

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

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

Three sentences, each with a distinct purpose: the action, the critical `id` constraint, and the deletion warning. No filler or repetition of schema details. Front-loaded with the primary action.

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 create tool with 6 parameters and no output schema, the description covers the key behavioral constraints (unique immutable id, no deletion) and points to the sibling for tag checking. It doesn't explain the return value, but no output schema exists and the annotations cover safety. The only minor gap is not mentioning that `applicationId` comes from list_applications, though the schema already says that.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that `id` is a Bridge SDK tag, unique within the game, and not changeable later — this is semantic context beyond the schema's 'tag' description. It also clarifies the deletion limitation, which helps the agent understand the lifecycle of the `id` 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 description states a specific verb ('Add') and resource ('a leaderboard to a game'), and clarifies the `id` field's role as a Bridge SDK tag. It distinguishes itself from sibling tools like list_leaderboards and update_leaderboard by noting deletion is unavailable and tags must be checked first.

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

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

The description explicitly tells the agent to check list_leaderboards for existing tags before creating, and warns that deleting a leaderboard is not available. This gives clear when-to-use guidance and an important exclusion, which is strong for a create tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint 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 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?

Beyond the readOnly/idempotent annotations, it discloses that the JSON is intentionally dynamic, fields may be added, missing/null never means zero, and the payload carries no server-generated conclusion. These are high-value behavioral traits an agent cannot 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?

Front-loaded with the core purpose, then constraints and the guide reference. Dense but every sentence carries information; no filler.

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

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

With no output schema, the description carries the return-value burden and does so well: it lists the fields to inspect (schema_version, period, freshness, coverage, sample sizes, warnings) and the dynamic nature of the payload. Complete for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds genuine meaning by specifying that dateFrom/dateTo are inclusive calendar dates spanning at most 31 days and by explaining the cursor as page.next_cursor. This goes beyond the schema's format-only descriptions.

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

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

States a specific verb and resource: aggregated telemetry returned for one game, explicitly framed as evidence with no server-generated conclusion. This distinguishes it from guide/checklist siblings, though it does not name the sibling alternatives directly.

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

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

Gives clear operational context: paginate via next_cursor until sufficient data is read, and consult get_game_telemetry_guide before instrumenting or interpreting. It stops short of stating explicit when-not-to-use conditions relative to other telemetry-adjacent siblings.

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, destructiveHint=false, so the safety profile is covered. The description adds substantive content-level transparency: what the guide defines (performance_sample contract, bounded progression events, custom-to-system migration, privacy rules) and why the JSON is dynamic. No auth or rate-limit concerns, which is appropriate for a static guide.

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?

Effectively two sentences, front-loaded with the identity of the resource and the imperative to read it, followed by a compact enumeration of contents. Dense but every clause names a distinct topic an agent would need to know the guide covers.

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

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

For a no-parameter, no-output-schema documentation tool, the description tells the agent what is inside the guide and when to read it. It could be slightly stronger by noting the guide has no side effects or that it must be read before a specific sibling (analytics), but the essentials 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?

Zero parameters, so per the rubric the baseline is 4. The schema is empty and the description correctly does not invent parameter semantics; nothing more can be said about arguments.

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 game telemetry guide) and its role ('agent-only instructions for instrumenting a Playgama game and interpreting its telemetry'). It also distinguishes itself from the sibling get_game_telemetry_analytics by positioning this tool as the guide that explains how to read that tool's output.

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 triggering condition: 'Read before finishing a game.' It also references get_game_telemetry_analytics as the dependency whose output this guide helps interpret. It stops short of stating when not to read it or naming alternative guides (e.g., get_bridge_sdk_docs).

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 tool read-only and idempotent; the description adds substantial behavioral detail: the full state set, UNKNOWN as retry-worthy, CABINET semantics, and traffic referral/share rules. It also clarifies that a completed traffic campaign closes the step permanently, which is non-obvious.

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

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

All sentences contain useful information, but the description is a single dense paragraph that would benefit from bullets or sections for the state enum and traffic rules. It is front-loaded with the main purpose, but readability suffers.

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 tool with no output schema, the description covers the return fields, state semantics, retry behavior, and special cases (traffic, bonus). It provides enough context for an agent to interpret and act on the launch path without seeing sample output.

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 already fully described in the schema ('as returned by list_applications'), and the description adds no parameter-level guidance. With 100% schema coverage, no additional compensation is needed.

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

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

The description clearly identifies the resource as 'the developer's path for the game' and enumerates the ordered steps (archive through traffic), so an agent can tell it returns the full launch path. It is distinct from single-step siblings like get_archive_status and get_sandbox_state, though it does not name them 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 provides operational guidance for retries ('UNKNOWN is neither done nor not done: call again', 'reuse the returned bonusId when retrying'), but it does not explain when to choose this tool over sibling status tools or when not to use it. The intended use is implied by the name and purpose, not 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 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context: the $3 traffic bonuses for accepted invitations and first successful publication, the eligibility window for accepting an invitation, and that bonuses are traffic budgets, not cash. It also clarifies that reading does not activate anything.

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 information-dense but well-structured, starting with the core purpose and then elaborating on eligibility, bonus mechanics, and usage workflow. Every sentence adds value; there is no fluff or repetition. It efficiently covers the what, how, and when.

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

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

For a read-only tool with no parameters and no output schema, the description fully covers what the agent needs: what it returns, how to share it, the bonus rules, and how to apply a bonus via a sibling tool. Nothing essential is missing for correct invocation.

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

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

The tool has zero parameters, so there is nothing to describe beyond the schema. The baseline for 0 params is 4, and the description appropriately omits parameter details since none exist. No additional semantics are needed.

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

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

The description states a specific verb ('Read') and a clear resource: the organization's stable invitation code/link, eligibility, counts, and bonuses. It distinguishes this from sibling tools like apply_referral_code and start_sandbox_traffic by focusing on the read-only nature and the specific data returned.

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 is no enrollment step and that every member can read it. It gives clear guidance on when to use this tool vs. when to use start_sandbox_traffic (for applying the bonus) and even mentions consulting get_sandbox_traffic. It also clarifies that reading alone does not start traffic, preventing 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?

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 declare readOnly, idempotent, non-destructive and closed-world, so the baseline is met. The description goes further with genuinely useful behavior: the meaning of a null return, the full semantics of changeStatus (CHANGED/UNCHANGED/UNKNOWN), that UNKNOWN never refuses, and that repeating the read is safe after an ambiguous publish.

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

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

The description is dense but every clause earns its place, packing return shape, conditional fields, enum meanings and the post-publish interpretation into a few sentences. The heavy backtick/em-dash compression hurts readability somewhat but avoids 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 carries the full burden of explaining return values and it does so thoroughly: what `site` contains, when it is null, what additional fields appear with `archiveId`, and how to interpret statuses after an ambiguous publish. Nothing essential for correct invocation or 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics beyond the schema: it names the fields `archiveId` unlocks (`publish` with allowed/reason/message/failedAt), explains changeStatus values, and ties `archiveChanged` to whether a new revision was created.

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 resource (the game's sandbox page) and discloses what the read yields (`site` with link/status/live revision, or null). It implicitly distinguishes itself from publish_sandbox by framing itself as the reader of the refusal that publish would give. However, it never explicitly contrasts its scope against other state-reading siblings like get_archive_status or get_sandbox_share.

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?

Usage is implied through the `archiveId` case (to learn whether a publish would be refused) and one explicit scenario: after a publish with no answer, to determine whether it landed. There is no explicit when-to-use versus alternatives and no when-not guidance, and no routing among the many sibling state tools.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, already covering safety. The description goes well beyond this by explaining the structure and semantics of the response, including verdict.reason codes and the actions to take for each, the referral offer's independence and capacity sharing, and polling guidance after starting traffic. This adds substantial behavioral context without contradicting annotations.

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

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

The description is long but well-structured, front-loaded with the core purpose before diving into field details. Each sentence provides necessary information for interpreting the complex response, and the reason codes are enumerated clearly. It is dense but appropriately so for the tool's complexity.

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 single parameter, the description carries the full burden of explaining the response. It covers verdict, offer, referralOffer, current runs, and runs list, including statuses, failure reasons, and post URLs, plus guidance on polling after starting traffic. Nothing an agent needs to call and 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?

The only parameter, applicationId, is fully described in the schema as 'Application (game) id, as returned by list_applications' (100% coverage). The description adds no additional meaning or usage context for this parameter, 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 tool reads the sandbox traffic state, including verdict, offer, and runs. The verb and resource are explicit, and the title reinforces this. It doesn't explicitly distinguish from siblings like get_sandbox_share, but the content makes the purpose unambiguous.

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

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

The description implies when to use the tool (to check if an ad campaign can bring players to the sandbox) and references get_bridge_sdk_docs for integration details, but it does not explicitly contrast with alternative tools or state when not to use it. The guidance is more about interpreting the response than selecting the tool.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds value beyond them by enumerating the possible `reason` categories and instructing the agent to relay `message` word for word — a real behavioral instruction, though it leaves the exact response shape unstated.

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 question and organized by output field. The `reason` enumeration is dense with embedded parentheticals, slightly slowing parsing, but every clause carries information.

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

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

With no output schema, the description carries the return-value burden and does so: it names the `reason` categories and explains `message` and `archiveId`. An agent has enough to call this correctly and interpret the result.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema, which itself explains that archiveId is the build a submit would name. The description's gloss ('the one a submit would freeze') largely restates the schema, so baseline 3 applies.

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

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

The description states a specific resource and question: whether the game can be submitted to moderation now and, if not, why. It distinguishes itself from the sibling get_archive_status by explicitly delegating archive reason codes there, so an agent can route correctly 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?

It conveys the operative context (checking a pending/blocked submission, relaying the refusal verbatim) and points to get_archive_status for archive-level reasons. It stops short of an explicit 'when not to use this' clause, so it's clear context but no stated exclusions.

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

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

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 cover the safety profile (destructive=true, readOnlyHint=false), and the description adds substantially more: instant unmoderated public exposure, preview caching on first open, the full reason list with per-reason remediation, and ORG_QUOTA with resetsAt plus an explicit 'wait, do not retry' instruction. There is a mild tension between the declared idempotentHint=false and 'repeating is safe / UNCHANGED (nothing written)', but that describes the post-first-call behavior rather than a real 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?

Front-loaded with the action and the key warning before any caveats, and the bolded cues make it scannable. It is long, but nearly every clause (per-reason remediation, the 'relay the message word for word' instruction, the 'never build the URL' rule) is directly actionable, so little is wasted.

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

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

Even without an output schema, the description documents the return contract (outcome PUBLISHED/UNCHANGED, url, revision), explains how to consume it (hand out url, never construct it), and names the follow-up tool (get_sandbox_share). Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns above it by explaining why archiveId must be in a specific state and version, tying the parameter to the check pipeline rather than merely naming it.

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

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

States a precise verb+resource+effect: publishes an archive to the game's sandbox and makes it publicly playable at once. The first sentence alone lets an agent distinguish it from sibling writes like start_archive_upload or confirm_archive_upload.

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 (get_archive_status state=PASSED, processing=DONE, Bridge >= 2.2.0), an alternative pre-check (get_sandbox_state with the same archiveId answers the refusal before this call), and a full refusal taxonomy that tells the agent exactly when the call will not succeed and what to do instead.

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

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

Beyond the destructiveHint annotation, the description details the exact destructive behavior: omitted products are deleted and an empty list clears the catalog. It also discloses the checksum-based refusal mechanism, which is not covered by annotations and is critical for safe invocation.

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 tightly written sentences with no fluff. The core behavior is front-loaded ('Replace the whole in-app catalog'), followed by the critical consequences and prerequisites. 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 destructive mutation tool with no output schema, the description covers all essential context: the replacement semantics, the destructive deletion behavior, the prerequisite read step, the checksum requirement, and the refusal condition. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context for `products` (the complete catalog, not a patch) and `expectedChecksum` (the checksum from list_in_app_products representing the state to replace), which goes beyond the schema's field-level descriptions and clarifies the interplay between parameters.

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

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

The description states a specific verb ('Replace') and resource ('the whole in-app catalog') with an explicit contrast to a patch, making the tool's scope unambiguous and distinguishing it from any patch-like sibling. It also explains the destructive consequence of omitting products, which further clarifies the operation.

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

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

The description explicitly instructs the agent to read list_in_app_products first and pass its checksum as expectedChecksum, and warns that the call is refused if the catalog changed. It also advises asking the developer before removing products, giving clear when-to-use and cautionary guidance without needing to name alternatives since the prerequisite tool is named.

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

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

Adds operational context beyond annotations: the response contains uploadUrl and headers, the PUT must use those exact headers and the exact byte length, and the URL expires within an hour, with a concrete curl example. It stops short of explaining the meaning of destructiveHint=true (e.g. what prior archive state is affected), but with annotations carrying the safety profile this is strong.

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 position, then prerequisite, then return contract and deadline, then next tool. Every clause is operative (checklist, uploadUrl/headers, one-hour window, example command) with no padding.

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

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

For a workflow-step tool with no output schema, the description supplies the prerequisite, the returned fields, the deadline, the transport mechanism, and the next step — everything an agent needs to invoke it and continue correctly.

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

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

Schema description coverage is 100%, so all three parameters (name, contentSize, applicationId) are already documented in the schema, including the size limit and version-naming convention. The description adds no parameter-level detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb+resource ('Step 1 of 3 of uploading a build') and names its position in a workflow, letting an agent distinguish it from confirm_archive_upload and start_cover_upload 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 tool (read get_game_checklist and check the build against each item first) and the follow-up tool (then call confirm_archive_upload), so the agent knows exactly when in the sequence 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?

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?

Beyond the annotations (destructiveHint=true, no idempotency), the description discloses rich non-obvious behavior: the $3 bonus is spent and reserved, a timeout is not permission to spend another bonus, uncertain DSP outcomes keep their reservation, requeueing reuses the same bonusId, and campaign budget/dates are extended on link additions. This greatly extends what annotations alone convey, with no contradictions.

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, but the description is very long and contains repetition ('extend it to at least three days from submission' appears twice, and 'up to three' claims recur). While the density is largely warranted for a money-spending tool with fail-safe rules, tighter editing would improve scannability without losing content.

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

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

For a high-complexity spending tool with no output schema, the description is remarkably complete: it covers preconditions, the PENDING → FAILED polling lifecycle with failureReason, specific error reasons (SHARE_REQUIRED, INVALID_POST_URL, PAYMENT_REQUIRED, RUN_IN_PROGRESS), and the paid-traffic fallback path. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all three parameters heavily. The description nevertheless adds value beyond the schema: the 'exactly one of bonusId/postUrls' mutual-exclusion rule, the one-campaign-per-game / three-games-per-org cap, and the linkage between adding links and increasing the same campaign's budget. Slight redundancy with schema text but still additive.

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 'Start an ad campaign that sends players to the sandbox page' names a specific verb, resource, and target, and the rest distinguishes the two traffic sources (referral bonus vs. share links). It is clearly separable from siblings like get_sandbox_traffic (status) and get_sandbox_share (post/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?

The description explicitly states when to use each parameter path (bonusId from get_referral_program/get_sandbox_traffic vs. postUrls after the developer publishes), names get_sandbox_traffic for polling, and gives hard preconditions ('Needs covers in the published revision and the Bridge SDK', 'Ask the developer first'). Alternatives and exclusions are spelled out, not 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 flag destructiveHint=true and non-idempotent, and the description adds the crucial nuance explaining what that means in practice: partial merge for scalars but wholesale replacement for enum arrays, plus the explicit non-submission guarantee. It omits permission/auth requirements and error behavior, 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?

Three short clauses, zero filler, and the partial-save rule is front-loaded where it matters most. 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 17-parameter mutation tool with no output schema, the description covers the two highest-risk ambiguities (merge semantics and whether it triggers moderation). Leave-one-field-out behavior and enum-array replacement are exactly what an agent needs; only auth/error framing 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 per-parameter descriptions (including enum label expansions), so the schema carries the burden and a baseline 3 is appropriate. The description adds only global merge semantics, not per-parameter detail beyond what the schema already provides.

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

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

States a specific verb+resource ('Save form fields of a game') and immediately qualifies it with the partial-save semantics, so the agent knows this mutates an existing application rather than creating one. It does not explicitly name the sibling it differs from (create_application), which keeps it at 4 rather than 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?

Gives clear operating context: omitted fields retain values, enum arrays are replaced whole, and nothing is sent to moderation. The 'does not submit' clause usefully routes the agent away from submission flows, but no explicit alternative tool (e.g. get_submission_state) is named.

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, so the mutation nature is covered. The description adds useful constraints: the tag cannot change and deleting is unavailable. It does not describe side effects or permissions, but the annotation coverage lowers the bar. Overall, it adds some context beyond annotations.

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

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

Two sentences, no fluff, key constraint 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?

Covers the essential scope and constraints for an update tool with no output schema. It doesn't mention success/error behavior, but that is not necessary given the annotations. The immutability and deletion limitations are stated.

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

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

The schema already documents each parameter with descriptions and 100% coverage. The description adds the critical constraint that at least one of name, type, or scoreOrder is required, and that leaderboardId (the tag) is immutable. This is valuable because the schema's required array only lists applicationId and leaderboardId.

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 the specific verb 'Change' and resource 'leaderboard', enumerates the mutable fields (name, type, scoreOrder) and explicitly lists what is off-limits (tag, delete). This clearly differentiates it from create_leaderboard and 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?

The description implies the tool is for updating an existing leaderboard and clarifies that at least one field is required. It does not explicitly name alternatives, but the context of sibling tools (create_leaderboard, list_leaderboards) makes the use case clear. Lacks explicit 'use this when' guidance, so not a 5.

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