publish

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

Annotations only indicate it's not read-only, not idempotent, and not destructive. The description adds rich behavioral context: drafts are private, no play link is returned, drafts are deleted after 7 days, the claim_url mechanism, and build-time advice about embedding and sizing. This fully informs the agent of what the tool does 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?

The description is long but front-loaded with the core purpose. Each sentence carries useful information, though the list of covered requests ('publish, share, post, put online...') is somewhat redundant. Overall, the length is justified by the tool's complexity and the need to clarify the publish flow.

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

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

Given the tool's complexity (7 params, nested objects, output schema), the description is thorough. It covers the draft lifecycle, account requirements, file limits, and layout advice. Since an output schema exists, not detailing return fields is acceptable. The description provides a complete mental model of how this tool fits into the publishing workflow.

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 86%, so the schema already documents parameters well. The description adds extra constraints and context not in the schema, such as '2.5 MB of files in total', 'an index.html at the top level is required', and the purpose of the optional cover image ('improves the game page and social share card'). This adds meaningful value beyond the schema.

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

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

The description clearly states the tool's function: 'Makes a private, unpublished draft of a browser game on Playfrog from static files.' It also distinguishes itself from sibling update_game_draft by noting that update replaces files of an existing draft. The phrase 'Covers requests to publish, share, post, put online...' clarifies the intended user requests it addresses.

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 maps user intents (publish, share, host) to this tool, and mentions update_game_draft as the alternative for replacing files of a draft made in the same session. It also provides prerequisites like requiring index.html and notes the publishing flow requires a Playfrog account, giving clear when-to-use guidance.

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

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

Even though annotations already declare destructiveHint=true, the description adds substantial behavioral detail: it replaces files completely, leaves the claim link functional, keeps the draft private with no play link, preserves the 7-day life, and explains the publishing flow. It also clarifies that the session constraint is a limitation of the tool, not the game itself. This goes well beyond the minimal annotation.

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

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

The description is a single dense paragraph, which is somewhat long but each sentence contributes meaningful operational context (session scoping, privacy, publishing, size limits). The main purpose is front-loaded. It could be slightly more concise, but given the tool's complexity and the critical caveats, the length is justified.

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

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

For a tool with 9 parameters, nested objects, and an output schema, the description covers all essential context: replacement semantics, session-only limitation, privacy implications, return behavior (no play link), upload requirements (complete files, index.html, size), and the unchanged publishing process. It even addresses the subtle point that the claim link from the original draft remains valid. This is highly complete.

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

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

The input schema already covers 89% of parameters with descriptions. The description adds value beyond the schema by explaining that 'Send the complete set of files again rather than a diff,' and highlights the required index.html and total size limit (2.5 MB). This enriches the files parameter semantics. The game_id parameter is also contextualized as the one returned by create_game_draft.

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 begins with a clear verb and resource: 'Replaces the files of a private, unpublished draft made with create_game_draft.' It specifies the exact scope (replacing files in an unpublished draft) and inherently distinguishes itself from the sibling create_game_draft by focusing on updates/revisions.

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: 'Covers requests to change, fix, revise or re-send a game that has not been published yet.' It also gives critical when-not-to-use guidance by emphasizing it only works within the same connector session that created the draft, and that a draft from an earlier session cannot be revised. This prevents misuse and clarifies the tool's limited applicability.

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