gamedev.pl

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

The description discloses that the reply includes stop and pendingMessages, and that it is a write operation, adding context beyond the annotations. It also mentions warnings codes like progress_stale, which are useful behavioral traits, but many of these are general workflow instructions not specific to ack_inbox.

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 excessively long and includes many instructions unrelated to acknowledging inbox messages, such as screenshot timing and file staging. It is not concise, and the core purpose is buried under several paragraphs of general guidance.

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

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

The description provides extensive coverage of the overall workflow, but much of it is irrelevant to ack_inbox itself. While it covers edge cases like stop and pendingMessages, the inclusion of unrelated instructions could mislead an agent about the tool's capabilities, so it is not optimally 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?

The description clarifies that ids are 'creator inbox message ids', compensating for the schema's lack of description for this parameter. The sessionKey parameter is already well-described in the schema, so the description doesn't need to add more.

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 clearly states the tool acknowledges creator inbox message ids after applying them, which differentiates it from read_inbox. However, the rest of the description dives into unrelated workflow steps (progress reporting, screenshots, staging), muddying the tool's core 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?

The description explicitly states when to use this tool ('after you have applied them') and provides guidance about when not to poll or continue. It implies alternatives like read_inbox for reading, though it doesn't explicitly name a different tool for 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?

Annotations mark destructiveHint=true, and the description adds substantial behavioral context: automatic clearing via submit_sources, no gate re-run during staging, honoring warnings like progress_stale/gate_not_started, and the need to end after submit. This goes well beyond the structured annotation fields and there is 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 a long, dense wall of workflow instructions covering progress reporting, screenshots, gates, inbox handling, seed status, and end() requirements. It is front-loaded with purpose, but not appropriately sized; many directives exceed what is needed for this tool's core clearing function.

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

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

The description covers numerous edge cases: automatic clearing, gate polling behavior, seed availability, inbox pendingMessages, stop conditions, and when to call end. Given the schema and annotations, it is extremely complete for the tool's role in the overall 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 coverage is 100%, so the baseline is 3. The description restates the paths parameter ('all paths, or only paths[]') but adds little beyond the schema. The sessionKey parameter is already well documented in the schema and the description does not add further meaning.

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

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

The description opens with a specific verb and resource: 'Clear the staging buffer (all paths, or only paths[])'. This clearly distinguishes the tool from siblings like stage_source_file, patch_source_file, and submit_sources by focusing on buffer reset rather than adding or delivering files.

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: 'Use before re-staging a clean tree', and notes that 'Successful submit_sources({ fromStaged: true }) also clears automatically', so agents know when explicit clearing is unnecessary. It also contrasts with alternatives like stage_source_file and patch_source_file for file edits.

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 provide idempotentHint=true, the description adds nuance ('Idempotent while a round is already open') and discloses return behavior ('Returns jobId only') and auth expectations ('Accepts Authorization: Bearer'). It also flags that feedback is treated as untrusted creator text. 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?

Three sentences deliver purpose, auth, exclusion, return behavior, and idempotency. Front-loaded with the core action, then relevant constraints. Every sentence earns its place with zero fluff.

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

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

Covers when to use, when not to use, auth prerequisites, next step, return value, and idempotency. The output schema exists to detail the jobId structure, so the description does not need to restate it. For a tool with this complexity, the description is complete.

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

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

Schema coverage is 100%, but the description adds essential meaning beyond the schema: slug is conditionally required ('Required with a creator-key or OAuth Bearer'), key is deprecated ('no longer accepted'), and feedback has a quoting/verbatim rule that affects how the parameter should be filled. This significantly boosts usability.

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 'Reopen an unpublished draft after a closed round,' a specific verb+resource pair that clearly defines the tool's scope. It also explicitly distinguishes it from a sibling tool: 'Not for published games — use open_round after publish.'

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

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

Provides clear timing guidance ('typically after a green gate'), explicit exclusion ('Not for published games'), a named alternative ('use open_round after publish'), and a next-step instruction ('call start() next for a sessionKey'). This is exemplary usage guidance.

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

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

The description discloses several behavioral traits beyond the annotations: auth requirements (Bearer creator key or OAuth), quota consumption ('same daily creation quota as Studio'), moderation, and return shape (slug and jobId only). This is valuable context that the annotations (only false hints) 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 four sentences, front-loaded with the primary purpose, then covers auth, quota, return value, and usage guidance. Every sentence contributes essential information with no redundancy or verbosity.

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 (3 params, output schema, sequential workflow), the description fully covers purpose, auth, quota, moderation, return shape, and the next step. It is sufficient for an agent to correctly select and invoke the tool.

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

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

The schema already describes all parameters (100% coverage), and the description adds operational meaning by instructing the agent to treat title and concept as the creator's words and to ask rather than invent. This goes beyond the schema's 'creator text' note, providing practical guidance for obtaining parameter values.

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

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

The description clearly states 'Create a new game on the creator's account and open its first build round', using a specific verb and resource. It distinguishes itself from siblings by noting the follow-up action ('call start({ slug }) next'), making the tool's role 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 provides strong contextual guidance: it tells the agent to call start next, and instructs to treat title/concept as the creator's words ('ask them, do not invent them'). It lacks explicit alternatives or when-not-to-use cases, but the sequential workflow is clear.

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

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

The description discloses important behavioral traits beyond annotations: it 'sets stop:true', 'closes your MCP session cleanly', and notes the key already retires after a green publish. It also warns 'Honour stop immediately — do not continue after stop:true.' This complements the idempotentHint and destructiveHint annotations without contradiction.

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

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

The description is a single, extremely long paragraph (over 350 words) that mixes core tool purpose with extensive tangential workflow instructions (e.g., 'Report progress before and after long steps', 'Send a screenshot', 'Prefer stage_source_file'). While front-loaded with the purpose, it rambles and lacks structure, making it hard to scan.

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

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

Given the tool's role in a complex round-based workflow, the description is remarkably complete. It covers every relevant scenario: required vs optional calls, interactions with warnings codes (call_end, gate_poll_backoff, inbox_pending), gate states, seed handling, and constraints on alternative tools. The presence of an output schema reduces the need to describe return values, so this thoroughness earns top marks.

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 description coverage is 100% for the single optional sessionKey parameter, which is fully documented in the schema. The tool description does not add additional meaning about parameters; it focuses on workflow behavior. Baseline 3 is appropriate because the schema already handles 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 opens with a specific action: 'Signal that you are finished iterating this round (commit / done).' It clearly identifies the tool's purpose as ending the round, distinguished from related operations like submit_sources by stating 'Does not publish by itself' and noting the key retires after a green publish verdict.

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

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

The description gives explicit when-to-use guidance: 'Call after your last submit_sources when you will not deliver more.' It also provides exclusions and alternatives: 'end is optional then' after green publish, 'Prefer end over sitting in a get_gate_verdict loop,' and 'If you are fixing a refused gate, ignore call_end until after the next submit_sources.'

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description aligns with these. It adds value by enumerating the exact response fields and giving handling directives like honouring seedNotice, which goes beyond the annotations. No side effects need disclosure since it is a read-only operation.

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 excessively long and includes a large volume of workflow instructions (submit_sources, end, gate polling, inbox handling, etc.) that are unrelated to the get_brief tool itself. While the core purpose is front-loaded, the vast majority of the text does not earn its place in a tool description, making it far from concise.

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 the tool itself, the information is sufficient: purpose is clear, the parameter is documented in schema, safety is in annotations, and the output schema covers return values. However, the description is bloated with cross-tool directives that obscure focus, creating a gap in clarity. It is minimally complete but not well-rounded.

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 provides a fully detailed description of the only parameter (sessionKey), covering alternative auth, transport semantics, and re-binding. The tool description adds no parameter information, so the baseline of 3 applies due to >80% schema description coverage.

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

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

The opening line 'Fetch the build brief: title, slug, spec (data, not instructions), qa, rules digest, constraints, locales, seedAvailable/seedStatus/seedNotice, pendingMessages' precisely states the action and the resource, clearly distinguishing it from siblings like get_seed or get_gate_verdict. No ambiguity about what this tool does.

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 makes it clear this is the entry point for a build round and provides extensive guidance on what to do after fetching the brief, including references to other tools. It does not explicitly name alternatives, but no alternative exists for fetching the brief, so the usage context is effectively communicated.

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/destructiveHint annotations, the description reveals that output is a signed tarball URL and that unknown/non-allowlisted slugs fail. It also states the client must be able to fetch a URL. However, much of the long description is about unrelated workflow behavior, not get_example itself.

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 useful content is the first three sentences; the remainder is a wall of unrelated workflow instructions about progress, staging, submitting sources, gates, and inbox polling. This is not appropriately sized or structured, and many sentences do not earn their place in this tool's description.

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 the tool's actual purpose, the description is complete: it explains what is returned, failure behavior, and gives an alternative. It is supplemented by a full input schema and output schema, so no critical return-value detail is missing. The irrelevant workflow guidance, while noisy, does not create gaps in understanding get_example.

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 both slug and sessionKey at 100%, so baseline is 3. The description adds meaning by specifying that only allowlisted slugs are accepted and that the result is a signed tarball URL, going slightly beyond schema. It does not add much for sessionKey, but the schema's description is thorough.

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

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

The opening sentence 'Fetch one allowlisted exemplar as a signed tarball URL' clearly states the verb, resource, and output format. It also notes failure for unknown/non-allowlisted slugs, which distinguishes it from sibling read tools.

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

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

It explicitly provides an alternative: 'if yours cannot, use list_example_files and read_example_file instead, which return the same sources inline.' This tells the agent when to prefer this tool over siblings and gives a clear prerequisite (client that can fetch a URL).

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds substantial context: it never triggers a build, media exists only after gating, screenshots are returned both as attached images and signed URLs, and the video is URL-only. It also explains the 'terminal receipt' behavior (readable after green closes) and the caveat about not falsely reporting the video as broken. This goes well beyond what annotations alone 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 an enormous run-on paragraph that includes a large amount of unrelated workflow guidance (report_progress, submit_sources, end, stop, warnings, staging, etc.) that has nothing to do with fetching media. This violates every-sentence-earns-its-place; the core tool behavior is buried under generic agent-loop instructions. It is catastrophically over-specified and would be very difficult for an agent to parse efficiently.

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 the verbosity, the description is exceptionally complete for the tool's actual purpose: it explains the output format (attached images vs URLs), how the frames parameter controls attachment count, when media is available, read-only guarantees, and the URL-handling caveat. An output schema exists, so return values are already covered. The description covers all practical scenarios and edge cases for using this media-fetching tool.

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

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

The input schema already provides full descriptions for all three parameters: frames (including enum meanings), deliveryId, and sessionKey (with security details). The description repeats the frames behavior ('opening (default) attaches one frame; frames=all attaches up to 3; frames=none skips them') but adds no new parameter-specific meaning beyond the schema. Thus, it meets the baseline for high schema coverage but doesn't elevate further.

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 clear, specific statement: 'Fetch the media the gate itself produced for a delivery (default: latest).' It specifies the resource (gate media) and the verb (fetch), and elaborates on screenshots and video. It lacks an explicit distinction from sibling tools like show_media, but the focus on 'the gate itself' and 'when you cannot run the game yourself' makes the purpose clear.

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

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

The description gives direct usage guidance: 'Use it when you cannot run the game yourself' and advises inspecting attached frames for defects. It also presents a precondition ('media exists only after a delivery has been gated') and an exclusion ('If your client cannot open URLs, do not try... hand the link to the creator'). However, it doesn't mention when to prefer an alternative like show_media, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds rich behavioral context: pending semantics with stop:true/false, retryAfterSeconds, terminal kit_outdated handling, backoff warnings, expiry impact, and the rule that only publish green ends the round. This goes far beyond what annotations convey.

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

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

The description is extremely long and repetitive. Key points like 'pending with deliveryId returns stop:true' and 'one-shot check not polling' are stated multiple times in different sections. While some length is justified by complexity, the structure is a dense block of run-on instructions rather than a concise, organized spec. It would benefit from bullet points and deduplication.

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, the description covers all critical contexts: verdict meanings, stop semantics, retries, warnings, terminal states, and integration with submit_sources, end, get_seed, and inbox handling. An output schema exists, but the description still adds valuable workflow context that is not deducible from the schema alone.

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 both parameters (deliveryId, sessionKey) with full descriptions, so the baseline is 3. The tool description adds context about deliveryId defaulting to the latest and the sessionKey being short-lived from start(), but these are minor additions over the schema. No parameter is left ambiguous.

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: 'One-shot check of the gate verdict for a delivery (default: latest)' and explicitly distinguishes it from polling/waiting. It also names the specific verdict values for preview and publish lanes, making its purpose unambiguous relative to sibling tools like get_proposal_status or get_gate_media.

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?

Extensive guidance is provided on when to use this tool vs. alternatives: it is positioned as a one-shot check never a polling loop, with explicit instructions to call submit_sources instead when deliveryId is null, and to stop immediately when pending with deliveryId set. It also names alternatives like get_seed, read_inbox, and end, and warns against repeated checks via gate_poll_backoff.

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 and idempotentHint annotations, the description discloses critical behavioral context: the tool returns metadata essential for submit_sources, warns not to pull the whole kit into context, notes that `cd` does not persist across tool calls, and details side-effects of the overall workflow (e.g., progress reporting, inbox draining, stop handling). These are non-obvious behaviors not captured by 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 a single massive block of text covering the entire workflow, far exceeding what is needed for a get_kit tool. While it is front-loaded with the core purpose, the bulk of the content pertains to other tools (submit_sources, end, get_gate_verdict) and general process rules, making it poorly structured and not appropriately sized for a tool description.

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 the verbosity, the description is contextually complete for the complex ecosystem: it explains the tool's role in the submission pipeline, how to handle warnings, seeds, inbox messages, gate states, and the need to call end, while also listing output fields. Combined with an output schema and strong annotations, the agent has all necessary context to use get_kit correctly.

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

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

The schema already fully describes the single optional parameter sessionKey with detailed semantics (short-lived capability, alternative to Bearer header, re-binding on session loss). The tool description does not add further parameter-specific details, and with 100% schema coverage, a 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 opens with a specific verb and resource: 'Fetch Creator Kit metadata' and lists the exact fields (engineRef, sha256, entry, kitUrl/unpack, browse tool names). It also distinguishes itself from siblings by explicitly recommending read_kit_files/list_kit_files for reading files instead of downloading the tarball, making the purpose unmistakably clear.

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 explicit when-to-use guidance: 'Prefer read_kit_files for several known small paths... over downloading the tarball' and also states when to avoid get_kit. It includes detailed workflow rules covering when to submit_sources, when to call end, how to handle gate verdicts, and when to use alternatives like get_seed, making usage scenarios and exclusions abundantly explicit.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context about status transitions and polling semantics, plus the fact that two statuses come with actionable guidance. This goes beyond the annotations without contradicting them.

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 front-loaded: the main purpose is stated first, followed by only the essential status interpretations. Every sentence earns its place with no redundant or filler 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?

Given that an output schema exists, the description does not need to detail return values. It explains the key statuses and their implications, which is sufficient for a low-complexity tool with one parameter. It could be slightly more complete by listing all possible statuses, but the provided information is likely adequate.

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

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

The schema has a single 'proposalId' parameter with 0% coverage from the description. The description does not explicitly explain the parameter, but the name and the phrase 'Where a proposal stands' make its purpose reasonably clear. It would benefit from mentioning the format or source of the ID, but minimal compensation is acceptable for such a self-evident 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 clearly communicates that the tool reports proposal status, using the phrase 'Where a proposal stands' and enumerating status values. It distinguishes itself from sibling tools by focusing on proposal-specific statuses, though it lacks a direct verb like 'get' or 'check' in the description itself.

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 actionable guidance: it tells users to poll when status is 'checking' and explains what to do for 'needs_work' and 'changes_requested'. It does not explicitly exclude alternatives or mention when not to use it, but the context is clear.

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

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

Annotations already declare read-only and idempotent, and the description adds meaningful status semantics (available/pending/unavailable), warning codes like seed_unread and module_too_large, and the instruction to continue the returned draft rather than scaffold. No contradiction with 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 an extremely long block of workflow instructions, many of which pertain to other tools (submit_sources, get_gate_verdict, end, read_inbox). It repeats the module_too_large warning twice and lacks bullet structure. The first sentence is strong, but the rest is not concise.

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 all relevant state branches for the seed fetch: available, pending, unavailable, warnings, and when to stop. The output schema handles return-value shape, while the description adds the decision logic an agent needs to act correctly after calling get_seed.

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, sessionKey, has 100% schema description coverage and is optional. The tool-level description adds no parameter detail, but the schema fully documents it, 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?

Opens with 'Fetch the platform-generated compiling seed draft for this round when present' — a specific verb, resource, and temporal scope. It also distinguishes from scaffold-from-kit and sibling continue_draft by spelling out when to continue vs re-check vs fall back to kit.

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

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

Provides explicit conditional usage: call when available, recheck when pending, only scaffold from kit when unavailable. It also gives workflow context around gates, submissions, and inbox, making the tool's place in the process 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 mark the tool as readOnly, idempotent, and non-destructive. The description adds the 'candidate or published' distinction and references warning codes like module_too_large and seed_unread. Much of the text is workflow guidance for other tools, which adds noise rather than deepening the tool's own behavioral disclosure.

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

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

The first sentence is front-loaded, but the description continues for several hundred words with instructions for report_progress, send_screenshot, submit_sources, end, and gate polling. Most sentences do not pertain to get_sources itself, making it inappropriately long for a simple fetch 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?

Despite the bloat, the description covers the core purpose, next steps after fetching, and warning handling. With an output schema present and annotations covering safety, the tool is adequately specified for an agent to invoke it correctly, though the extraneous content reduces clarity.

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% with descriptions for version and sessionKey. The description does not add extra parameter semantics beyond 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 opening sentence clearly states the tool fetches the latest candidate or published sources for the job's game to continue prior work. This is a specific verb+resource and distinguishes it from related seed/brief tools, though it does not name alternatives.

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

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

The description gives clear context: use it when a self round needs to continue prior work, and it mentions 'do not scaffold from scratch' when a seed is available. It also warns about splitting oversized modules and following up with submit_sources. However, it does not explicitly contrast with sibling tools like get_seed or continue_draft.

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 is covered. The description adds meaningful behavioral context beyond those: it avoids downloading the tarball (a performance/network trait) and mentions the allowlisted restriction. This adds value 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 front-loads the core purpose in one clean sentence, but then appends a massive block of workflow instructions about staging, gates, submission, and inbox handling that is unrelated to invoking list_example_files. Many sentences do not belong in this tool's description, making it overlong and difficult to scan.

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

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

For a simple listing tool, the first sentence plus the complete input schema and output schema are sufficient to understand invocation and expected results. The description also conveys the key constraints (allowlisted, no tarball download). However, the added workflow content is not scoped to this tool and slightly detracts from focus, so it is not a perfect 5.

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 every parameter (slug, limit, offset, prefix, sessionKey) already has a clear description in the input schema. The tool description itself adds no extra parameter-specific meaning, so it stays at the baseline of 3 for a fully schema-documented tool.

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

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

The description opens with a specific verb and resource: 'List the source files inside an allowlisted exemplar game, without downloading its tarball.' This clearly distinguishes it from siblings like get_example (which returns a link) and list_examples (which lists exemplars, not files). The resource and action are explicit and 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 states when to use this tool: 'Use this (and read_example_file) when you cannot fetch URLs — get_example returns a link that a client without shell or network access cannot follow.' This directly contrasts with get_example and names the alternative, giving the agent clear decision 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 readOnlyHint and idempotentHint. The description adds one useful constraint ('never creator-originating sources') but otherwise buries relevant behavior under extensive, unrelated workflow directives. There is no direct contradiction with annotations, but transparency is weak because the description does not clarify pagination, result shape, or filtering semantics.

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 extremely long and packs dozens of sentences about submitting sources, running gates, and ending rounds—none of which relate to list_examples. Although the purpose sentence is front-loaded, the overwhelming majority of content is irrelevant, making the description bloated and difficult to parse.

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 read-only list tool, the first sentence plus annotations and output schema could be sufficient, but the massive amount of unrelated workflow text makes the description incomplete and misleading. It omits practical details like whether filters are combined with AND/OR and instead instructs the agent to call submit_sources, end, and other tools, which risks incorrect 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 only 25% with just sessionKey documented, so the description must compensate for genre, module, and feature. The phrase 'Filter by genre/feature/module when provided' adds basic filter semantics, but there is no detail about value formats, combination logic, or defaults. sessionKey is handled well in the schema, but the other three parameters remain under-specified.

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

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

The opening sentence clearly states the tool lists curated first-party exemplar games and excludes creator-originating sources, which is specific and distinguishes it from file-level siblings like list_example_files. However, the remainder of the description pivots to an unrelated game-creation workflow (submit_sources, stage_source_file, end), muddying the overall 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?

The only usage guidance is 'Filter by genre/feature/module when provided,' which is minimal and does not explain when to prefer this tool over get_example or list_example_files. The bulk of the description gives instructions for other tools and actions, providing no useful when-to-use or when-not-to-use context.

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

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

Annotations already declare read-only and idempotent; the description adds useful context about the engineRef requirement to avoid mixing kit revisions and reveals that results include file size and kind. However, this is buried under a massive workflow narrative unrelated to the tool's own behavior.

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

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

The description is a wall of text containing extensive instructions for the entire delivery workflow (progress reporting, staging, submission, gate handling, inbox draining) that do not belong in this tool's description. It lacks bullet points or any structural separation, making it exceptionally hard to parse.

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 listing tool, the core information (what it lists, pagination, engineRef requirement) is present, but it is drowned out by irrelevant workflow rules covering every other tool in the system. The description would be far more complete and usable if it were trimmed to just the first sentence plus parameter/pagination notes.

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 six parameters are already described. The description redundantly mentions prefix/glob and pagination but adds no new semantic meaning 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?

The first sentence clearly states the tool lists paths inside a pinned Creator Kit with size and file kind, distinguishing it from read_kit_file and search_kit_files. The verb 'List' and resource 'paths inside a Creator Kit' are specific and actionable.

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 no explicit guidance on when to use list_kit_files versus alternatives like search_kit_files or read_kit_files. Most of the usage guidance focuses on other tools (stage_source_file, submit_sources, end) rather than this listing tool, leaving the agent to infer when to invoke 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=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavior: it only returns paths, not contents; it confirms staged changes before submission; and it notes that staging does not re-run the gate. This exceeds the annotation baseline without contradicting 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?

The core purpose is front-loaded in the first sentence, but the description quickly expands into a long block of unrelated workflow directives (progress reporting, screenshots, gate handling, inbox draining, end-call rules). This is overlong and obscures the tool's immediate semantics.

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 read-only tool, the description provides extensive workflow context, including ordering relative to stage/patch/submit, relevant warning codes, and stop conditions. The output schema exists, so return-value details are not needed. It is more than complete for its purpose.

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, sessionKey, is fully documented in the input schema (100% coverage), so the schema carries the semantic weight. The description adds no parameter-specific detail, matching the baseline of 3 for high schema coverage.

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

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

The description opens with 'List paths currently in the staging buffer (no contents)', a specific verb+resource that clearly states what the tool does and distinguishes it from get_sources (which reads contents) and clear_staged_sources. The scope is 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?

It explicitly says to use this tool after stage_source_file/patch_source_file and before submit_sources, with a concrete invocation example. It does not explicitly name get_sources as the alternative for reading file contents, but the 'no contents' qualifier and workflow placement give strong 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?

The description adds meaningful behavioral context beyond the annotations: it is a non-committal action (nothing is sent until submit_proposal), it returns working sources, and it requires the game to have contributions enabled. It also notes the owner may decline. These details align with the idempotentHint and destructiveHint=false annotations, and add value about side effects and prerequisites.

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 three sentences, front-loaded with the primary action, and every sentence adds necessary information: what it does, what it returns, what does not happen, and a prerequisite. 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?

The description covers the essential context: the target audience (games you do not own), the output, the non-committal nature, and the requirement for contributions to be enabled. With an output schema present and simple parameters, this is sufficient for an agent to understand the tool's role and when to invoke it.

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

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

The input schema already has 100% coverage with descriptions for all three parameters (slug, title, description). The tool description does not add any additional parameter semantics beyond what the schema provides, so 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 opens with a specific action: 'Open a proposal against a published game you do NOT own.' This clearly distinguishes it from sibling tools like open_round (likely for own games), and it states the key outputs (sources and a proposalId). It is not a tautology and names a concrete resource and 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?

The description says when to use it (against a published game you do not own), and gives an important exclusion: 'The game must have contributions enabled.' It also clarifies the tool's role in a sequence by stating 'Nothing is sent until you call submit_proposal,' implicitly positioning this as the first step. It does not explicitly name sibling alternatives, but the 'do NOT own' phrasing effectively contrasts with open_round.

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 meaningful behavioral facts beyond annotations: quota spending, returns only jobId and requires a follow-up start() call, idempotency while a round is open, and the critical warning that feedback is treated as untrusted creator text that must be quoted verbatim. These are non-obvious and safety-relevant details that annotations alone would 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?

Four compact sentences front-load the purpose, then sequentially cover auth, side effects, return value, next step, and idempotency with no wasted words. Every sentence carries essential 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?

Given the tool's complexity—auth modes, quota, sequential workflow, idempotency, feedback handling—the description covers all critical operational facts. The output schema handles return-value details, but the description still explicitly notes 'returns jobId only — call start() next', making the tool safely usable.

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

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

Schema coverage is 100% and already documents slug requirements, the deprecated key parameter, and the feedback length/untrusted-text note. The description's auth summary ('Accepts Authorization: Bearer') adds a small layer of context but largely restates schema content, so it meets the baseline.

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

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

The description clearly states the specific action ('Open a new post-publish improvement round') and target ('on a published game'), which distinguishes it from the sibling open_proposal_round. The verb, resource, and scope are all explicit.

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 clear applicability context: the game must be published, auth is via Bearer (creator key or OAuth), and the round consumes the same daily improvement quota as Studio. It does not explicitly say 'use this instead of open_proposal_round', but the post-publish scope and sequential guidance ('call start() next') imply the intended workflow.

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 note destructiveHint: true, and the description adds many behavioral specifics: 'old must match exactly once', 'Do not pass patch together with old/new', 'Staging does not re-run the gate', and rules about gate verdicts, stop flags, and pendingMessages. This goes far beyond the annotation flags.

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 long, dense wall of text covering entire workflow rules far beyond this tool's immediate action (submit_sources, end, inbox, gates). It repeats the fromStaged overlay detail twice and includes many tangential instructions. While detailed, it is not concise nor well-structured for at-a-glance parsing.

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

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

The description is extremely comprehensive, covering parameter alternatives, error conditions (warnings.code values), gate states, inbox handling, seed behavior, and required follow-up calls. With an output schema present, this fully equips an agent to use the tool in its context.

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 83%, so baseline is 3. The description clarifies the old/new replacement mechanism ('exact unique substring replace'), the patch alternative, and the constraint that old must match exactly once. However, it omits any mention of the 'slug' parameter, leaving a small gap.

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 'Edit ONE existing path in the staging buffer without re-uploading the whole file' – a precise verb, resource, and scope. It also contrasts with stage_source_file, which is for new/rewritten files, making the tool's specific role clear.

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 says 'Prefer this over stage_source_file whenever the file already exists' and 'Prefer stage_source_file for new/rewritten paths and patch_source_file for edits', giving direct decision rules. It also details when to use old+new vs patch and when to submit.

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 readOnly/idempotent, so the description adds value by disclosing inline behavior, binary encoding requirement, refusal of large files, and path conventions. The later workflow instructions go beyond this tool's core behavior but do not contradict annotations.

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

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

The bulk of the description is unrelated workflow guidance (progress reports, submit_sources, gates, inbox, seeds) that makes it far too long for a simple read tool. While the opening is front-loaded, the remainder is unfocused and hard to scan.

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

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

Given the output schema and annotations, the description covers the tool's operational details (binary, large files, path forms) and even embeds broader protocol context. It is complete, though arguably too much; no critical gaps remain.

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 covers all parameters, but description adds path format guidance (relative vs full), encoding semantics, and 'no fetching required' context. This enhances the schema without redundancy.

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?

Clearly states 'Read one file from an allowlisted exemplar game' with a specific verb, object, and scope. It distinguishes itself from sibling write tools (stage_source_file, patch_source_file) by describing reading inline with no fetching.

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

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

Provides context on when to use: paths come from list_example_files, supports relative/full paths, binary encoding, and large-file refusal. It gives alternatives only for writes, but does not explicitly exclude read_kit_file; still clear enough.

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

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

Annotations only declare readOnly/idempotent/non-destructive, but the description adds detailed behavioral semantics: stop:true based on deliveryId, gateStarted meanings, seedStatus handling, warning codes like inbox_pending and gate_not_started, and explicit instruction to honor stop immediately. This far exceeds the annotation baseline.

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 lengthy operational manual covering submit_sources, staging, gates, end, seeds, progress reporting, and many sibling workflows. While the core purpose is front-loaded, the majority of sentences are not specific to read_inbox and would be better placed in a global briefing, making it excessively bloated.

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 the verbosity, the description is contextually complete for a tool with this complexity. It covers stop semantics, pendingMessages, deliveryId, seed status, warning codes, gate modes, and the required end call. Since an output schema exists, lack of return-value documentation is acceptable.

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 sessionKey parameter is fully documented in the schema with transport and auth context, so description adds no parameter-level meaning. With 100% schema coverage, the baseline score 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?

Purpose is explicit and action-oriented: 'Read pending creator messages and control (stop).' It distinguishes itself from sibling ack_inbox by describing read/control behavior and clarifies that mutating tools piggyback pendingMessages rather than replacing this tool.

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

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

Provides explicit when-to-use guidance: 'Prefer this when idle' and 'when that array is non-empty, read_inbox and apply before continuing.' It also gives clear exclusions: no background polling, drain piggybacked pendingMessages, and stop immediately on stop:true.

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

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

Beyond the readOnly/idempotent hints, the description discloses the size limit, the specific error 'kit_file_too_large', the need for base64 encoding for binary files, and the rationale for passing engineRef to prevent kit revision mixing. These are meaningful behavioral traits not present in the annotations.

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

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

The description is extremely long and mostly contains generic workflow guidance (e.g., reporting progress, ending rounds, handling gate verdicts) unrelated to reading a file. Only the first two sentences are directly relevant. This is a severe violation of conciseness and effective structuring.

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 the tool's core behavior, it is complete: it covers size limits, error conditions, encoding, sibling alternatives, and parameter usage. The presence of an output schema means return values need not be described. However, the extraneous workflow noise slightly detracts from completeness, though it doesn't create gaps.

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

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

The schema already covers all 4 parameters, so the baseline is 3. The description adds value by explaining why engineRef should be passed, when to use base64 encoding, and the context for binary files. This enhances the schema descriptions without duplicating them.

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 clearly identifies the action and target: 'Read one small Creator Kit file (≤48 KiB).' It also explicitly distinguishes from siblings by recommending read_kit_files for multiple paths and read_kit_file_fragment for larger files, showing precise 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?

It gives explicit decision rules: prefer read_kit_files for several known paths, use read_kit_file_fragment when the file exceeds 48 KiB, and require base64 encoding for binary files. This directly answers when to use this tool versus 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 readOnlyHint/idempotentHint annotations, the description discloses window semantics (lines/bytes, base64), pagination via nextOffset, errors on overlong line windows, the need for engineRef, and even warns about gate/progress behavior. This is rich behavioral detail that does not contradict 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 first sentence is concise, but the description becomes a massive wall of text covering progress reporting, screenshots, staging, submission, end calls, gate verdicts, seeds, and inbox handling—most of which is unrelated to reading a file fragment. This is over-specified and rambling.

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 its verbosity, the description is exceptionally complete: it covers pagination, error modes, engineRef consistency, base64/bytes behavior, and even the broader delivery workflow that an agent needs to handle. With output schema and strong annotations present, no important context 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 input schema already describes all 7 parameters with 100% coverage, so the description adds only modest value. It reinforces engineRef sourcing and pagination via offset, and adds the overlong-window error behavior and the byte/base64 pairing, which go slightly 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 first sentence clearly states the tool reads a window of a Creator Kit file by lines or bytes, with a specific verb, resource, and scope. This distinguishes it from sibling tools like read_kit_file, list_kit_files, and search_kit_files.

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

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

Provides clear usage guidance: pass engineRef from get_kit, use nextOffset for pagination, and switch to unit=bytes when line windows are overlong. However, it does not explicitly contrast this tool with read_kit_file or state when to prefer one over the other, and much of the description veers into broader workflow instructions.

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, and the description adds significant behavioral detail: per-path failures stay in files[], aggregate size limit, and encoding defaults. It also explains responses carry pendingMessages and how to handle different seed/gate states, all 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 excessively long, comprising a dense block of workflow instructions spanning gates, staging, submission, inbox, seeds, and reporting. While the initial sentence is clear, the majority of the content is tangential to the read operation itself, making it not concise.

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

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

The description is exhaustive, covering success and failure modes, interactions with stage_source_file/patch_source_file, gate behavior, inbox handling, and stop semantics. It effectively provides a complete operational manual for when this tool is used as part of a larger 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 100%, so the baseline is 3. The description adds little beyond the schema for parameters themselves; it mentions 'Pass engineRef from get_kit' but the schema already contains that instruction. It does add output-related context (per-path failures) but that is not 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 opens with 'Read up to 12 small Creator Kit files in one call (≤128 KiB aggregate)', clearly stating the verb, resource, and key constraints. It distinguishes itself from read_kit_file and read_kit_file_fragment by referencing those sibling tools 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 explicitly advises 'Prefer this over repeated read_kit_file to stay within per-turn tool-call limits' and notes that 'Oversized files need read_kit_file_fragment'. It also gives prerequisite guidance like 'Pass engineRef from get_kit' and describes when to stop or continue based on gate states.

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 provide no behavioral hints (all false), so the description carries the full burden. It discloses that replies include stop and pendingMessages, explains language handling with textLocalized/locale, and reveals nuanced behaviors like 'Staging does not re-run the gate' and 'Every write reply carries pendingMessages' — far beyond annotation capabilities.

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 extremely long and contains redundant guidance, such as repeating 'Call before and after long steps' and interleaving many other-tool instructions. While the first sentence front-loads the core purpose, the sheer volume and repetitive workflow details make it more of a manual than a concise tool description.

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 and the sparse annotations, the description is remarkably complete. It covers localization, response handling, gate checks, staging behavior, end-of-round protocols, and inbox draining, ensuring an agent has enough context to use the tool correctly in nearly all scenarios. The output schema also relieves the need to document return values.

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 description adds meaning for step (lists the enum values) and for textLocalized/locale (explains the cheap path) and text (accepts any language). However, it does not explain the done and total parameters at all, even though schema descriptions for them are absent, leaving a 57% coverage gap partially uncompensated.

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

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

The description opens with a specific action and resource: 'Report a build-progress update to the creator thread.' It immediately distinguishes itself from siblings by specifying the step enum and explaining the response includes stop and pendingMessages, making the tool's role clear.

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

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

It gives explicit when-to-use guidance: 'Call before and after long steps' and when warnings carry progress_stale. It also contrasts with related tools (stage_source_file, patch_source_file, submit_sources, end) and provides a full workflow, leaving no ambiguity about 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds case-insensitive matching and a capped match count, which are useful beyond the annotations. No contradictions, but the large amount of unrelated workflow boilerplate dilutes the behavioral disclosure.

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

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

The description front-loads a good purpose sentence, but the remaining hundreds of words are generic workflow instructions (progress reporting, staging, submission, end) irrelevant to a file search tool. This is severely over-sized and violates the 'every sentence earns its place' principle.

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 the core search operation, the schema, output schema, and initial sentence provide enough. However, the inclusion of extensive unrelated workflow context creates noise and may confuse an agent about the tool's actual scope and side effects.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning by noting query matching is case-insensitive and specifying that engineRef should come from get_kit, which is not in the schema.

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

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

The first sentence clearly states the tool's function: 'Search text files in a pinned Creator Kit for a substring (case-insensitive).' It also specifies the return shape and a cap on matches, which distinguishes it from sibling list/read tools.

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

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

It provides a clear prerequisite ('Pass engineRef from get_kit') and the search use case is implicit from the first sentence. However, it does not explicitly mention when not to use this tool versus list/read alternatives, or name any 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?

The description goes far beyond the annotations (all false) by disclosing reply contents (stop, pendingMessages), warning codes (progress_stale, module_too_large, must_fix_gate, call_end, gate_not_started, etc.), progress reporting requirements, and how to handle seeds, inbox, and stop semantics. This is a rich behavioral contract.

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, extremely dense paragraph that mixes every possible rule without any bullet points, headings, or logical separation. It repeats key instructions (e.g., 'as soon as the game draws' appears twice, 'Do not stop after submit alone without end' appears near the end). While every sentence carries some weight, the lack of structure hurts readability and front-loading.

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 its verbosity, the description is exceptionally complete for a tool that interacts with a complex delivery pipeline. It covers edge cases (gatling warnings, seed status, inbox draining), exit conditions (when to end, when to ignore call_end), and integration with submit_sources and gate verdicts. The output schema presumably handles return-value structure, so the description's coverage 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 descriptions already cover png, pngBase64, and sessionKey; label and caption have no descriptions in the schema. The tool description adds no parameter-specific guidance—it repeats the size limit already present in the schema and never explains label or caption. With 60% schema coverage, the description should compensate but does not.

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 purpose: upload a PNG screenshot with size and format constraints, and specifies when to send it ('as soon as the game draws'). It distinguishes itself from siblings like report_progress and submit_sources by focusing on screenshot delivery.

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

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

Provides explicit timing ('as soon as the game draws anything playable'), mode requirements ('mode=preview'), and workflow sequencing with sibling tools ('Prefer stage_source_file for new/rewritten paths', 'after submit_sources, if you will not deliver more this round, call end'). Also includes when-not-to behaviours like 'Do not stop after submit alone without end'.

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

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

The description discloses numerous behavioral traits beyond annotations, such as 'Only clients that render MCP Apps views show anything,' the need to 'Send a screenshot as soon as the game draws anything playable,' and the warning-handling rules (e.g., 'Honour warnings.code=progress_stale'). It also clarifies that 'Staging does not re-run the gate; the creator card stays on the refused delivery until you submit' and 'Do not schedule background or recurring inbox polls.' This far exceeds the minimal read-only 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 very long, dense paragraph covering not just the tool's purpose but an entire operational workflow involving submit_sources, end, gate verdicts, inbox polling, and seed handling. While front-loaded with purpose, the lack of bullets or sections makes it hard to scan. Many sentences could be split into structured guidance without losing value.

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

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

Given the tool's complexity and interdependence with many sibling tools, the description covers every critical interaction: when to call get_seed based on seedStatus, when to call end after submit_sources, how to honor stop:true, gate verdict handling, and warning codes. The output schema exists, so return values don't need explanation, and no operational gaps are apparent.

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 provides 100% coverage with descriptions for deliveryId and sessionKey, including defaults and authentication alternatives. The description adds little parameter-specific detail beyond restating that it 'Defaults to the latest delivery,' which is already in the schema. Baseline 3 is appropriate since no 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 opens with a specific verb and resource: 'Render the gate's screenshots for a delivery in the creator's chat, at a size they can actually look at, with the gameplay recording and a link to play.' It also distinguishes itself from the sibling get_gate_media tool by explaining that get_gate_media's attachments are for the agent, not the creator. This makes the tool's role 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 states 'Use this when the creator asks to see the game' and contrasts it with get_gate_media. It also provides extensive context on when to call end/submit_sources, use preview mode, handle warnings, and interact with seed and inbox states, giving clear decision 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?

The description provides rich behavioral detail (self-refresh, stops on settle, second call duplicates, depends on MCP Apps client), but it directly contradicts the idempotentHint:true annotation by stating 'a second call renders a second card.' This means repeated calls have a different effect, so the tool is not idempotent as annotated. Per the rubric, this contradiction forces a score of 1.

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 extremely long (roughly 700 words) and packs in many directives about other tools (submit_sources, report_progress, end, get_gate_verdict, get_seed, read_inbox). While the main purpose is front-loaded, the bulk is an unstructured workflow dump that should not live in one tool description. This is over-specification, not concise guidance.

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

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

Despite the length, the description covers an extensive range of contextual edge cases: self-refresh lifecycle, gate verdict semantics, preview vs publish, end-call requirements, inbox pending messages, seed availability, and client rendering limitations. Since an output schema exists, not describing return values is acceptable. It is complete, if not well-organized.

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

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

The schema already provides 100% coverage for the single sessionKey parameter, including usage, fallback via Authorization header, and transport correlation. The description adds no parameter-specific information beyond what the schema states, 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?

The opening sentence uses a specific verb+resource: 'Render a live status card for this round in the creator's chat' and enumerates its contents (phase, progress note, screenshot, gate verdict, deliveries left). It also distinguishes itself from siblings by noting it is a self-refreshing display tool and explicitly warns against calling it twice.

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

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

The description gives explicit when-to-use guidance: 'Call it ONCE per round, after start — a second call renders a second card.' It also explains what it does NOT do: 'show_round alone does not re-run the gate,' 'Staging does not re-run the gate,' and directs the agent to prefer end over polling loops. These are clear usage rules versus alternative 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?

Beyond the destructiveHint annotation, the description discloses key behavioral traits: 'Overwrites the same path if staged again' and the critical side effect that 'staging alone does not re-run the gate' — you must submit again. It also describes how fromStaged overlays onto the latest delivery, adding meaningful context beyond 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 an extremely long, single-block paragraph (likely 600+ words) that mixes tool-specific guidance with broad workflow rules about end(), get_gate_verdict polling, seed handling, and inbox draining. Although the first sentence is front-loaded, the rest is a sprawling wall of text that would benefit from trimming and structuring.

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 position in a complex staging/gating pipeline, the description covers an extensive range of scenarios: when to stage, what staging does and doesn't do, interaction with submit_sources, gate states, progress reporting, and seed handling. It is arguably overcomplete, but it ensures an agent has enough context to operate effectively, even if some instructions are better placed elsewhere.

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 60% (path, content, sessionKey documented; slug and encoding not). The description adds that content is a 'full rewrite' and advises splitting large files, which gives some parameter context. However, the slug parameter remains entirely undocumented in both schema and description, and encoding semantics are only inherited from the schema, so the description only partially compensates for the gaps.

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: 'Upload ONE game source file into this round’s staging buffer (full rewrite).' It immediately differentiates from siblings by naming patch_source_file for edits and submit_sources for bulk uploads, making the tool's purpose unmistakable.

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

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

Explicit usage guidance is provided: 'Prefer this for new files; for edits to an existing path prefer patch_source_file' and 'Prefer over a giant submit_sources files[]'. It also states the follow-up action: 'Call once per path, then submit_sources({ fromStaged: true, mode, kitEngineRef })', giving clear when-to-use and next-step context.

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?

This contradicts the annotations: idempotentHint is true, yet the description says calling start again leaves a duplicate status card and is wrong. True idempotency would not create duplicates or side effects on retry. Even though the description is rich in behavioral detail, the explicit contradiction forces a score of 1 per the rubric.

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 it is front-loaded with the core purpose and session rules. It covers many complex workflow requirements in dense prose without obvious filler. It could benefit from structured bullets, but given the complexity, it is appropriately sized and information-dense.

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

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

The description is exceptionally comprehensive: it covers auth, session expiry, retry cases, side effects, progress reporting, staging vs patching, gate handling, seed flow, inbox draining, and end-of-round behavior. It fully compensates for the tool's complexity, and an output schema exists for return values. The only flaw is the annotation contradiction, which is captured separately.

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 key and slug. The description restates the authorization combinations but adds little beyond the schema, aside from contextual advice like keeping the sessionKey for the whole round. This meets the baseline for high schema coverage but does not exceed 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?

The description opens with a specific action: bind this MCP client to a build round, and details the three authentication forms (creator key + slug, legacy round-scoped key, OAuth Bearer + slug). This clearly differentiates start from siblings like continue_draft or open_round by establishing it as the one-time session-binding entry point.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: call it ONCE per round, do not call again before each operation, and re-run only if a call is refused as unauthenticated. It also gives workflow alternatives such as preferring end over polling get_gate_verdict and preferring stage/patch for source changes, making usage context very 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?

The description goes beyond annotations by revealing that submissions go through the same gate as a creator's delivery, requiring polling, and that a red gate returns to the sender without the owner seeing it. These are non-obvious behavioral consequences not captured by the idempotentHint or destructiveHint 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 three sentences, all dense with relevant information and no filler. It opens with the primary action and then packs in critical constraints and workflow in a logical order.

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 two parameters, the description covers what to send, how to send it, and what to do after (polling and gate outcomes). Since an output schema exists, return values are likely documented elsewhere. It could be slightly more explicit on when to use this over submit_sources, but overall it is adequate for the tool's complexity.

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

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

The schema has no parameter descriptions, and the description adds general meaning by referring to 'changed sources' and a 'complete file set', which relates to the files parameter. However, it does not explain the structure of the files array or the proposedId linkage in detail. This partially compensates for the 0% schema coverage but lacks per-parameter specifics.

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 sends changed sources for an opened proposal, using a specific verb ('send') and resource ('changed sources for the proposal'). It distinguishes itself from patching by explicitly saying 'not a patch', which differentiates it from sibling tools like patch_source_file.

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 tells the agent to send the complete file set rather than a patch, which implicitly steers away from patch_source_file. It also prescribes a follow-up action: poll get_proposal_status until it leaves 'checking'. It does not explicitly list alternative tools but gives enough contextual guidance for the intended workflow.

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

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

The description discloses numerous behavioral traits not covered by annotations: delivery cap, filename allowlist, gateStarted semantics, stop/pendingMessages handling, warning codes (call_end, progress_stale, module_too_large, etc.), and progress reporting requirements. It also clarifies that the operation is destructive/write-only, matching the destructiveHint=true annotation 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 extremely long and dense, covering a wide range of scenarios in a single unbroken paragraph. While every sentence carries useful operational detail, it lacks sectioning or bullet points, making it harder to scan. It is front-loaded with the core purpose, but overall it is more of a manual than a concise tool description.

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, the description is exceptionally complete: it covers prerequisites, workflow integration with siblings (stage_source_file, patch_source_file, get_kit, end), edge cases (kit_outdated, refused gates, seed availability), warning code handling, and progress reporting. Since an output schema exists, the description appropriately focuses on behavior rather than return values.

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 description adds substantial meaning beyond the schema: files[] is optional when fromStaged/fromLatestDelivery, inline paths override staged content, and kitEngineRef is required. It clarifies mode defaulting behavior ('publish except with fromLatestDelivery reuses the previous lane') and the ≤200 file limit, filling gaps in the schema's 63% coverage.

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

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

The description opens with 'Deliver game sources', a specific verb and resource that clearly identifies the tool's function. It distinguishes itself from sibling staging tools like stage_source_file and patch_source_file by framing itself as the delivery step, and mentions the gate, which is the unique target.

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

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

The description gives explicit when-to-use guidance: prefer staging tools then fromStaged=true for changed paths, use fromLatestDelivery for kit_outdated without re-upload, and clearly distinguishes mode=preview vs mode=publish. It also specifies when to call end and when not to, and contrasts with sibling tools like get_gate_verdict and report_progress.

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