gamedev.pl

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

Annotations already mark it as non-readOnly (write), destructive, and idempotent. The description adds value beyond annotations: it discloses that the reply includes stop and pendingMessages for concurrent visibility. It also clarifies idempotent behavior is implied by acknowledging already-applied messages. No contradictions 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?

Two sentences that front-load the core purpose and immediately follow with key behavioral detail. Every sentence earns its place with no 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 output schema exists, so return value explanation is not needed. Considering the tool's complexity (write, destructive, idempotent, with concurrent polling concern), the description covers the critical behavioral aspects. Could mention that it requires prior application of messages, but overall adequate for agent selection.

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 50%, with ids only documented by schema properties (type, maxItems). The description doesn't elaborate on ids beyond what's in the schema. The sessionKey parameter has good schema documentation, so the description adds no further meaning. Baseline 3 is appropriate given moderate 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 clearly states the tool acknowledges creator inbox message IDs after applying them. It distinguishes itself from read_inbox by specifying this is a write operation that consumes messages. The verb 'acknowledge' is specific and the resource is clearly the inbox messages.

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 indicates when to use it ('after you have applied them'). The sibling read_inbox contrasts nicely. However, it does not explicitly state when NOT to use it or provide alternatives for cases like batch processing or error handling.

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 destructiveHint=true, so the description does not need to restate destructiveness. It adds value by noting the automatic clearing behavior after a successful submit_sources call, which is useful behavioral context beyond what annotations provide.

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

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

Two sentences, no filler. The action is front-loaded, and every sentence earns its place by stating the action, a usage hint, and a behavioral note.

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 simplicity (2 optional params, destructive, output schema present), the description covers purpose, usage context, and a relevant behavioral detail. It does not explain return values, but an output schema exists. A minor gap is that it doesn't explicitly mention it clears source files from staging, but the title 'Clear staged source files' and sibling context fill that in.

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%, setting a baseline of 3. The description reinforces the paths parameter ('all paths, or only paths[]') but does not add new meaning beyond what the schema already provides ('Optional subset to clear; omit to clear everything.'). The sessionKey parameter is not mentioned in the description, but its schema description is detailed.

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 action ('Clear the staging buffer') and the optional scoping to specific paths, which distinguishes it from related siblings like stage_source_file (adding) and submit_sources (submitting). The verb 'clear' and resource 'staging buffer' are specific 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 says 'Use before re-staging a clean tree', providing a concrete scenario. It also notes that submit_sources({ fromStaged: true }) automatically clears, which helps an agent understand when manual clearing is unnecessary. However, it does not mention when not to use this tool or explicitly compare with alternatives like list_staged_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?

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?

Annotations already indicate destructive and non-idempotent behavior. The description adds nuance (e.g., removing entirely vs. empty content, resetting to default for certain files) but does not mention error handling or side effects on missing files. Slight gap.

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 bit verbose but each sentence adds value—clarifying the contrast with stage_source_file and specific use cases. It is well-structured and not redundant.

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 sufficient context for typical usage, including distinctions from related tools and default behavior for special files. It does not explain return values, but that is not critical given the operational nature.

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 descriptions fully cover the parameters (path and sessionKey) with clear explanations. The tool description adds no additional semantic detail, so baseline 3 applies as per guidelines.

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: explicitly removing a file from the delivered game, contrasting it with stage_source_file and providing a concrete example of the effect. This distinguishes it from sibling 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?

Provides explicit when-to-use guidance: retire old modules, clear leftover index.html or GAME.json fields, and notes that index.html cannot be re-staged. This is actionable and 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?

Goes well beyond annotations: explains that end closes the MCP session cleanly, doesn't publish by itself, that the key 'already retires' after a green publish verdict, and crucially that any text written after this call is never seen by the creator. Also discloses the round-handoff semantics (agentEndedAt) and the transport session re-binding behavior. No contradiction with annotations (readOnlyHint=false, idempotentHint=true aligns with 'optional' 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?

Densely packed with information — every sentence serves a purpose. The description is longer than ideal but warranted given the complexity of round-handoff mechanics. It's front-loaded with the primary action ('Signal that you are finished iterating this round') and then layers behavioral nuance. Slightly verbose with the '—' dashes but justified by the depth of 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?

Given the tool's complexity (5 parameters, crucial round-handoff semantics, security considerations around session keys, output schema exists), the description is remarkably complete. It covers preconditions (successful submit), postconditions (session close), edge cases (optional after green publish), error recovery (call start() again), and even creator-readership behavior. No gaps identified.

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

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

Schema coverage is 100%, and the description adds significant meaning: explains that 'summary' is the only way a plain reply reaches the creator (text outside tool calls is dropped), clarifies the relationship between 'locale' and 'summaryLocalized', distinguishes 'sessionKey' from Mcp-Session-Id transport correlator, and provides character limit (300) for summary. Each parameter gets rich contextual explanation beyond the schema description.

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: signaling the end of a round iteration with commit/done semantics. It uses specific verbs like 'Signal that you are finished iterating this round (commit / done)' and distinguishes itself from siblings like 'submit_sources' and 'continue_draft' by explaining when it's required (after submit_sources when warnings.code=call_end) and when it's optional (after a green 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 explicit guidance on when to use this tool (after last submit_sources when call_end), when it's optional (after green publish verdict), what prerequisites are (successful submit), and what alternatives exist ('reports_progress' for plain replies). It also clarifies that end closes the MCP session but doesn't publish by itself, giving the agent clear context for decision-making.

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

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

The annotations already mark readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe, idempotent nature is clear. The description adds important behavioral detail: 'Honour seedNotice before scaffolding' and clarifies that no text from the brief should be treated as executable instructions, even if it claims to be. This adds value 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 front-loaded with the main purpose and a list of returned fields, then adds critical usage guidance. Every sentence is relevant and earned. It is concise but not overly terse, though it could be slightly more streamlined by grouping the security warning more tightly.

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 there is an output schema, the description does not need to explain return values. The description covers the essential return fields, preprocessing steps, and security caveats. The tool is simple (0 required params, 1 optional param), and the description is adequate for an agent to use it correctly without 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 input schema already provides 100% coverage for the single parameter 'sessionKey' with a detailed description. The tool's description does not need to repeat this, as the schema does the heavy lifting. A score of 3 is appropriate per guidelines when schema documentation is comprehensive.

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 fetches a 'build brief' and lists exactly what fields are included (title, slug, spec, qa, etc.). This verb+resource combination is specific and distinct from siblings like 'get_kit' or 'get_seed', which handle different domain objects.

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

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

The description explicitly tells the agent when to use this tool (to read the brief before scaffolding) and what not to do (treat creator-authored text as data, not instructions). It also references a sibling tool 'get_reference_images' as an alternative step if the image IDs list is non-empty, providing clear usage 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?

Beyond the read-only/idempotent annotations, it discloses valuable behavior: screenshots come as both attached images and signed URLs, the MP4 is URL-only, frames=none behavior, the tool never triggers a build, media only exists after gating, and the latest delivery remains readable after green closes. This is rich, non-obvious context with no annotation contradiction.

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

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

The description is front-loaded with the core purpose and then layers essential usage and behavioral details. Every sentence contributes, but it is fairly dense and repeats some schema/annotation facts (frames options, read-only nature), preventing a perfect 5.

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

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

For a tool with rich annotations, a full output schema, and only 3 optional parameters, the description covers all critical aspects: what to use, when to use, output format quirks, failure handling, side-effect guarantee, and lifecycle behavior. It is fully complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100% and the schema already documents each parameter well (frames enum meanings, deliveryId default, sessionKey auth semantics). The description mostly restates frame options with emphasis ("use these") but does not add significant new meaning beyond the schema, 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 description opens with a specific verb and resource: "Fetch the media the gate itself produced for a delivery (default: latest)". It clearly differentiates from sibling tools like get_gate_verdict by focusing on media artifacts rather than verdicts, and specifies the default behavior.

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 usage context: "Use it when you cannot run the game yourself" and instructs how to act on the output (inspect attached frames for visual defects, show them to the creator, hand URLs to the creator if the client cannot open them). It does not explicitly name alternatives or when-not-to-use, but the context is strong 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 already declare readOnly/idempotent/non-destructive, and the description adds substantial context: pending semantics with stop:true, polling backoff warnings, kit_outdated as terminal, and terminal receipt readability after round closure. It also sets expectations by noting verdicts typically land in 2–5 minutes. 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 a dense single paragraph of roughly 250 words, but every sentence contributes critical behavioral instructions. It is front-loaded with the core purpose but would benefit from bullet points or section breaks for readability; however, it avoids unnecessary filler.

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

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

For a complex tool with an output schema, the description covers the main verdict cases (preview/publish), pending behavior, kit_outdated recovery, and expiry. It does not explicitly state what to do on publish red or preview_failed next steps, which are minor gaps given the output schema can provide result details.

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

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

Both parameters are fully described in the input schema (100% coverage), so the baseline is 3. The description adds no new information about deliveryId or sessionKey beyond what the schema already provides; the deliveryId:null references in the description are about result output, not the input 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 opens with 'One-shot check of the gate verdict for a delivery (default: latest)', clearly identifying the action and resource. It also distinguishes itself from polling/waiting tools by explicitly stating 'this is not a polling or waiting tool' and differentiates lanes (preview vs 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?

It gives explicit when-not-to-use guidance ('not a polling or waiting tool') and concrete alternatives: for a pending result with deliveryId:null, 'continue building and call submit_sources instead of checking again', and for kit_outdated, 're-run get_kit, then submit_sources'. It also warns against repeated checks with 'warnings.code=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?

Annotations already declare readOnlyHint and idempotentHint, and the description adds the pinning behavior (repeat calls return same engineRef), the semantics of kitEngineChanged, and the note that `cd` does not persist across tool calls. These are concrete behavioral details not inferable from annotations.

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

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

The description is long but tightly packed; each sentence covers a distinct fact or alternative. It is front-loaded with the core fetch action and then elaborates on usage variants, though the density makes it slightly less concise than ideal.

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 output schema covers return values, while the description supplies essential context about engine pinning, kitEngineChanged meaning, tool routing, and shell egress behavior. No significant gaps remain for the agent to invoke and react 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 only parameter sessionKey is fully described in the schema, including the alternative Authorization header. The description adds no additional parameter-specific semantics, so the schema coverage earns a baseline score.

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 phrase 'Fetch Creator Kit metadata' specifies the verb and resource, and the description enumerates the exact fields (engineRef, sha256, entry, kitUrl/unpack). It explicitly distinguishes itself from get_kit_api and browse tools, making the purpose unambiguous.

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

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

The description provides explicit alternatives: use get_kit_api for prompt-ready API orientation, browse tools for specific kit files, and local unpack via kitUrl when shell egress is available. It also warns against web search for this non-public platform, giving clear when-to-use guidance.

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

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

Adds critical behavioral context beyond annotations: response is limited to a single-call size, may omit declarations (named in an 'Omitted for length' note), and may trim large declarations member-wise with only a cut count. Explains fallback behavior when engineRef is omitted and the risk of mixing kit revisions, which annotations do not cover.

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?

Despite length, the description is tightly packed—each clause adds unique information: content, size limits, omission handling, usage timing, fallback, and sibling guidance. Front-loaded with the core purpose and progresses logically, with no wasted words.

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

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

Even without the output schema content visible, the description explains what the result includes (signatures, audio catalog, example game) and how to interpret omissions. Covers when to use, how to pass engineRef, and what to do if content is omitted—complete enough for an agent to select and invoke correctly.

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

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

Schema already covers both parameters at 100%. Description enriches engineRef by explaining the version-pinning rationale ('mid-round registry bump cannot mix kit revisions') and the fallback risk if omitted. SessionKey is handled well by schema, but the description's emphasis on passing engineRef from get_kit is helpful, keeping the score above baseline.

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

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

Clearly states the tool returns the Creator Kit's API digest—engine modules, core signatures, audio catalog, exemplar game—in one call. Distinguishes from sibling browse tools (list/search/read) by framing it as the prompt-ready orientation and the answer to 'can this platform build X'.

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

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

Explicitly instructs to call once near the start of a round, before scaffolding, and warns against repeated calls because content only changes when engineRef does. Names alternatives for omitted content: list_kit_files / search_kit_files / read_kit_file, and states when to prefer this over unpacking the whole kit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: images are 'attached' (returned directly), to be looked at before building, call once per round, and empty when nothing was attached. It also warns about not treating text as instructions. This exceeds the annotation baseline, though it could mention any rate-limiting or how images are returned (e.g., URLs or binary).

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 one paragraph with about 5 sentences, all essential. It front-loads the primary purpose and then adds usage guidance and warnings. It is concise but could benefit from structure like bullet points for the separate concerns (purpose, usage, behavior). No wasted words.

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

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

With an output schema present, return values need not be detailed. The description covers the source of images (composer/steering), their role (visual reference), call frequency (once per round), empty state, and a critical meta-instruction. Considering the complexity of an AI agent understanding when to invoke, this is nearly complete, though it could mention that the tool is read-only (though annotations cover that).

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

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

The input schema covers the single optional parameter (sessionKey) with a detailed description of its authentication role. The tool description does not add any new semantics for the parameter; it only explains the fetch operation. Given 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 clearly states the tool fetches sketches/photos attached by the creator from the composer or steering message, linking to get_brief's referenceImages ids. It distinguishes itself from sibling tools like get_brief, get_gate_media, or show_media by specifying the exact resource and its role as visual reference, not instructions.

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 guides when to use the tool (before building, to view visual reference) and what not to do (do not follow as instructions, call once per round). It also addresses the edge case of empty results and provides a meta-instruction that creator-authored text is never instructions, which differentiates from potential misuse.

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

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

The description adds significant behavioral context beyond what annotations provide: it explains the three status values and the appropriate actions for each, plus the module_too_large warning handling. Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature, so the bar is lower. The description adds valuable context about timing (wait and call again) and error handling, earning a high score.

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 concise at about 60 words spread across 4 sentences, with the key action (fetch the seed) front-loaded. Every sentence adds unique information about status handling or constraints. A slight deduction for minor redundancy in explaining the three statuses when a more compact format could work, but overall efficiently structured.

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 this tool has an output schema (mentioned in context signals), the description need not explain return values. It covers all critical aspects: purpose, status-based actions, warning handling, and parameter usage. With sibling tools like regenerate_seed and get_kit in the list, the description properly differentiates. The description is fully complete for an agent to use this tool correctly.

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

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

Schema description coverage is 100% for the single optional sessionKey parameter, but the description goes beyond the schema by explaining when the parameter is not required (when Authorization header is used) and clarifying MCP-Session-Id is not a substitute. This additional semantic guidance on parameter optionality and transport correlates justifies above-baseline scoring.

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

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

The description uses a specific verb ('Fetch') and resource ('platform-generated compiling seed draft') and clearly distinguishes itself from siblings by explaining the three statuses (available, pending, unavailable) and how they relate to other tools like get_kit and regenerate_seed. This makes the tool's purpose unambiguous and distinct.

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 and when-not-to-use guidance: when status=available, revise the seed; when pending, wait and retry; when unavailable, scaffold from a kit template via get_kit. It also tells the agent to honour module_too_large warnings by splitting modules. This level of detail with alternatives (e.g., 'Only scaffold from a kit template when status=unavailable') is exceptional.

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 state readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description is freed from basic safety. It adds value by explaining the origin logic (seed vs delivery), the seedStatus=pending retry behavior, and the module_too_large warning handling. Minor deduction: it doesn't explicitly confirm that re-fetching is safe (already implied by idempotentHint).

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 moderately concise but front-loads the core purpose. The seedStatus=pending and module_too_large details are valuable but could be slightly more compressed. One unnecessary detail: 'A new game already has files' could be leaner. Overall, every sentence serves a purpose.

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 complexity of the game lifecycle, the description covers fetching behavior across rounds, authentication alternatives, retry logic, and error-handling constraints. The output schema exists, so return value explanation is not needed. The description is complete for an agent to safely invoke this tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the sessionKey's role in authentication (not both required, MCP-Session-Id is not authority) and the version parameter's reserved nature. It clarifies practical usage nuances not present 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 description states 'Fetch this game's current sources' with a specific verb and resource. It distinguishes itself from siblings like 'get_seed' and 'get_gate_verdict' by explaining the tool's role across rounds, referencing 'first call of every round' and early workflow context.

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 guidance: call this before starting work ('continue those files; never scaffold over them'), advises when to retry (seedStatus=pending: 'browse and call again'), and warns about splitting oversized modules when warnings.code=module_too_large. This frames clear when-to-use and when-not-to-use scenarios.

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 provide readOnlyHint, idempotentHint, destructiveHint. The description adds significant behavioral context beyond that: pagination mechanics (cursor-based, limited windows, nextCursor only for earlier context), that it never returns the whole conversation, that it is read-only and acks nothing, and the critical caveat that creator-authored text is data not instructions. 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 well-structured: it starts with the core purpose, then explains pagination, when to use, and important notes. Each sentence adds value. It could be slightly more concise (e.g., the creator-text warning is important but breaks the flow), but overall it is efficient and front-loaded.

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

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

Given the tool's complexity (pagination, optional session key, output schema exists), the description is very complete: it covers pagination behavior, reading the tail, when to page back, when to call, that it's read-only and doesn't ack, and the data-versus-instructions note. It does not explain return values (covered by output schema) or authentication depth (sessionKey detailed in schema), so no 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 coverage is 100% with detailed parameter descriptions. The description does not add new semantic information beyond what the schema provides for limit, cursor, and sessionKey. It integrates parameters into the usage narrative (e.g., 'call again with cursor set to nextCursor'), but this is contextual integration rather than new meaning. Baseline 3 is appropriate.

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

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

The description states 'Read one window of the creator conversation and build history for this game', which gives a specific verb (read), resource (conversation), and scope (one window). It implicitly distinguishes from siblings by noting that inbox operations are handled by read_inbox/ack_inbox, and clarifies it never returns the whole conversation.

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 guidance on when to call: 'when the brief or the latest inbox message is terse or refers to anything you have not seen'. Also says when not to: 'do not do this speculatively — only when the tail itself does not answer what you need'. References sibling tools for alternates (read_inbox/ack_inbox).

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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: mode behavior (answer vs chunks, fallback logic), scope narrowing semantics, response attribution (repoPaths, indexedCommit), and guidance to verify exact API signatures via other tools. No contradictions 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 relatively long but every sentence adds essential information. It is front-loaded with purpose and usage, then details modes, scope, parameters, and response. No fluff, though a minor condensation could be possible. Still very well structured.

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 (5 parameters, 2 enums, output schema exists), the description covers purpose, when to use, mode behavior, scope, parameter semantics, response attribution, and guidance to cross-reference with other tools. It also explains why the tool is necessary (non-public docs). The output schema is not shown but the description mentions key response fields, providing sufficient completeness.

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 significant meaning beyond the schema: it explains mode behaviors and fallback, defines each scope enum value, clarifies engineRef's purpose (prevents revision mix-ups across calls), and details sessionKey's relationship to Authorization and transport session. This extra context is highly valuable for correct invocation.

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 specifies a clear verb ('Ask a natural-language question'), a specific resource domain ('GameKit, EditorKit, the allowlisted example games, or platform docs/process'), and explicitly distinguishes from sibling tools like get_kit_api and browse tools. It also explains why this tool is needed (docs are not public).

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 ('for capability and “how do I…” questions that get_kit_api and the kit browse tools do not cover') and provides a strong exclusion ('Prefer get_kit_api first for kit API surface questions'). It also explains the mode options and fallback behavior, giving clear contextual guidance.

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

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

Annotations already mark the tool as read-only and idempotent, so the description only needs to add context. It discloses the output kind (size + text/binary kind) and the entry-point navigation pattern, which goes beyond 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 four short sentences, front-loaded with the main purpose, and every sentence adds value (purpose, prerequisite, filtering, entry point). No fluff 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?

Given that an output schema exists (so return structure is covered elsewhere), the description sufficiently addresses the workflow: engineRef requirement, optional prefix/glob, pagination, and how to begin traversal. It is complete for a read-only listing tool with well-documented parameters.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds only generic references to prefix/glob and pagination, which are already well-explained in the schema properties (including examples). No significant extra meaning beyond the schema is provided.

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

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

The description uses a specific verb+resource ('List paths inside a pinned Creator Kit') and adds useful details (size + text/binary kind) that clarify what is returned. It doesn't explicitly name sibling tools for differentiation, but the listing behavior is clearly distinct from read/search operations.

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 context on prerequisites (pass engineRef from get_kit) and workflow (start from get_kit.entry via read_kit_file). Does not explicitly exclude alternatives like search_kit_files or read_kit_files, but the instructions are sufficient for the intended use case.

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

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

Annotations already declare readOnly and idempotent behavior, so the description need not repeat that. It adds meaningful behavioral context: the tool returns only paths, not contents, which is a key trait not captured by annotations. It also implies a workflow role (confirmation step), adding value beyond the safety profile.

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

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

The description is two sentences, front-loaded with the core purpose and followed by practical usage context. Every word earns its place, with no redundancy or 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?

Given the tool's simplicity, existing annotations, and a rich output schema, the description is complete. It states what the tool returns, clarifies what it does not return, and explains when to use it in the broader workflow. 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?

The schema provides 100% coverage for the single optional parameter sessionKey, fully describing its meaning and usage. The description does not add parameter-specific details, but the schema carries the weight, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: listing paths in the staging buffer, explicitly noting it excludes contents. This distinguishes it from sibling tools like get_sources or read_staged_contents, and the verb 'list' is specific 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 gives explicit workflow guidance: use after stage_source_file or patch_source_file, and before submit_sources with fromStaged:true. This clearly positions the tool relative to its siblings and tells the agent 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?

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 declare destructiveHint=true, which the description corroborates by noting edits are mutating (replacing content). The description adds critical behavioral context beyond annotations: replacements apply sequentially per file, earlier edits can affect later matches, edits that apply are kept even if later ones miss, and the agent should honour warnings.code=patch_incomplete. It also explains the required follow-up call submit_sources({ fromStaged: true, ... }) and that fromStaged overlays onto the latest delivery/seed. 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 front-loaded with the core purpose and preference advice, then organized into clear pattern sections with explicit 'PREFERRED:', 'ALTERNATE:', and follow-up instructions. It is dense but efficient—almost every sentence adds value. It could potentially be shortened by removing redundant emphasis (e.g., 'PREFERRED' and 'prefer this over' are slightly duplicative), but remains highly functional.

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 8 parameters, a non-trivial output schema, and the complexity of multiple edit modes, the description covers all essential behavioral and workflow aspects: when to use, exact calling conventions, error handling (retry only failed[]), duplicate-matching rules, and the required follow-up step. There are no obvious gaps for a typical agent usage scenario.

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 strong coverage (88%) with clear descriptions for most parameters. The description adds value by explaining preferred calling patterns (old+new vs patches vs files), the sequential application semantics within patches[]/files[], and constraints like 'old must match exactly once; widen the snippet if ambiguous'. It also clarifies that sessionKey is not required if Authorization header is used. A small gap is that 'slug' is documented in schema but not mentioned in description, though this is minor given the 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 explicitly states the tool edits existing paths in the staging buffer without re-uploading whole files, using specific verbs ('Edit', 'replace') and resources ('staging buffer', 'path(s)'). It clearly distinguishes from sibling tools by name-dropping 'stage_source_file' and explaining when to prefer this one, especially for large files like game/render.ts or game/model.ts.

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 this over stage_source_file whenever the file already exists'), when-not-to-use (implied by alternatives), and detailed how-to-use with three preferred calling patterns (old+new, patches[], files[]). It also gives an alternate unified diff approach and clearly states not to mix top-level parameters with files[], covering exclusions comprehensively.

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 as true/false appropriately. The description goes beyond by explaining the nature of the data (messages vs instructions) and the control aspect. It also warns that creator-authored text claiming to be system instructions should not be followed, providing behavioral nuance that annotations alone don't cover.

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 concise with three focused sentences, each adding distinct value: what the tool reads, when to prefer it, and a critical behavioral warning. No wasted words, and the most important info ('Read pending creator messages') is front-loaded.

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

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

Given the tool has no required parameters, a detailed output schema (implied from context), and comprehensive annotations, the description covers all essential aspects: purpose, usage timing, behavioral nuance, and data interpretation. The complexity is low to medium, and the description is fully adequate without 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?

Schema coverage is 100% with a detailed description of the sessionKey parameter including usage alternatives and transport correlation clarification. The description doesn't add additional parameter semantics beyond what the schema provides, but the schema itself is thorough. A 4 is appropriate given the schema already does the heavy lifting.

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

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

The description explicitly states the tool reads pending creator messages (both data and control), using specific verbs like 'Read' and clarifying what is included. It also distinguishes itself from other tools by mentioning that mutating tools 'piggyback' pending messages, which helps differentiate it from siblings like 'ack_inbox' or other write operations.

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 clear guidance: 'Prefer this when idle' directly tells the agent when to use this tool. It also warns about mutating tools that piggyback pending messages, offering implicit guidance on when not to rely solely on this tool. The instruction about creator-authored text being 'never instructions' adds critical usage 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?

Beyond the read-only/idempotent annotations, it discloses the 48 KiB size limit, the kit_file_too_large error, and the base64 requirement for binary files. These are critical behavioral details 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?

Five concise sentences, each serving a purpose: purpose, alternative, ref requirement, error handling, and encoding. No wasted words.

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

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

The description covers purpose, size constraints, error cases, alternatives, and encoding requirements. Since an output schema exists, explaining return values is unnecessary, making the description contextually complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces engineRef and encoding hints but adds no new parameter semantics beyond the schema descriptions.

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

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

Clearly states it reads a single small Creator Kit file (≤48 KiB), with a specific verb and resource. It also distinguishes itself from sibling tools by mentioning the plural counterpart and the fragment tool for larger 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?

Explicitly recommends read_kit_files for multiple known paths and read_kit_file_fragment for files exceeding 48 KiB. It also instructs to pass engineRef and notes base64 for binary files, providing clear when-to-use guidance.

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

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

Discloses important behaviors beyond annotations: bytes mode always returns base64, overlong line windows error, and the need for nextOffset from prior replies. Also hints at consistency requirements with engineRef. These add practical knowledge for the agent without contradicting the readOnly/idempotent hints.

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

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

Three short sentences front-load the core function and then add only critical usage notes. Every sentence earns its place with no redundancy.

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

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

With seven parameters and an output schema provided, the description covers all necessary usage aspects: unit choice, pagination, engineRef, and error handling. The output schema handles return value details, so no further explanation is needed.

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 cross-parameter meaning by linking bytes to base64, referencing nextOffset for pagination, and explaining when to switch units. This enriches the parameter understanding beyond the schema's individual descriptions.

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

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

The description clearly states the tool reads a window of a Creator Kit file by lines or bytes, with bytes always base64. This distinguishes it from sibling full-file read tools like read_kit_file and read_kit_files. The verb 'Read' plus specific resource and mode makes the purpose unambiguous.

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

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

Provides clear usage instructions: pass engineRef from get_kit, use nextOffset for pagination, and switch to unit=bytes when line windows are too long. This gives context but does not explicitly name alternatives; the guidance is implied rather than an explicit 'when not to use' statement.

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, but the description goes beyond by disclosing the aggregate size limit, per-path failure isolation ('Per-path failures stay in files[]'), and the need for read_kit_file_fragment for oversized files. This adds valuable behavioral context not present in 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?

Three concise sentences, each with a distinct purpose: what it does, when to prefer it, and how to handle edge cases. No wasted words; front-loaded with the core capability and limits.

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 batched read tool with a rich schema and annotations, the description covers all operational context: limits, alternative tools, engineRef requirement, failure semantics, and output structure hint. Completely self-sufficient for an agent to invoke correctly.

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

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

Schema covers all parameters with descriptions, giving baseline 3. The description adds extra semantic meaning by mentioning the 1–12 path count, engineRef source (from get_kit), and the consequence of oversized files. Slight but meaningful addition over schema.

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

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

The description clearly states the tool reads multiple Creator Kit files in one call, with specific limits (up to 12 files, ≤128 KiB aggregate). It distinguishes itself from siblings by explicitly referencing read_kit_file and read_kit_file_fragment, making its unique role obvious.

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 guidance: 'Prefer this over repeated read_kit_file' and 'oversized files need read_kit_file_fragment.' This directly tells when to use the tool versus alternatives, satisfying the highest bar for usage direction.

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

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

Goes well beyond annotations by disclosing that it returns immediately with status=pending, that generation takes minutes, that it is refused under certain conditions, and that passing steer is required to avoid repeating the same result. This is critical behavioral context not expressed in readOnlyHint/destructiveHint.

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

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

The description is dense but efficiently structured, opening with the core purpose, then usage constraints, timing behavior, and refusal handling. No filler or redundant phrasing; each clause earns its place despite the length.

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

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

Given the output schema covers return values, the description fully addresses usage context, failure modes, timing, and alternative actions. It explains edge cases (refusal, poll behavior) and gives actionable guidance, making it complete for a nuanced 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?

While schema coverage is 100%, the description adds substantial meaning to the steer parameter by explaining that without it the same references are picked and the same draft returns. It does not add to sessionKey, but the steer insight elevates the parameter semantics above schema alone.

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: ask for a replacement round-0 draft when the current one is unusable, with specific conditions ('status=unavailable' or 'does not match the brief'). It distinguishes from siblings like get_seed by framing this as a regeneration request rather than a retrieval.

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

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

Explicitly states when to use it (unusable draft) and when not to (not a poll; refused once staged files or delivered). Names get_seed as the alternative to check later and advises continuing from existing work if refused, giving clear decision guidance.

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

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

Annotations only provide basic hints (readOnlyHint=false), so the description carries the burden of behavioral disclosure. It mentions that the reply includes 'stop' and 'pendingMessages', adding some transparency. However, it does not disclose mutability, idempotency, or auth requirements beyond what the parameter schema covers, leaving gaps in side-effect awareness.

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

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

The description is two sentences, front-loaded with the core purpose in the first sentence, and additional details in the second. Every sentence provides essential information without redundancy or filler.

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

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

Given the tool has 7 parameters and an output schema, the description covers the high-level purpose and step values but omits explanations of the integer parameters (done, total) and the relationship between text and textLocalized. The output response is only hinted at ('stop and pendingMessages'). While the detailed parameter schema provides some compensation, the description alone is not fully complete for an agent to use without consulting the schema.

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

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

With 57% schema description coverage, the description adds value by listing the step enum values again, reinforcing the schema. However, it does not explain the integer parameters 'done' and 'total', nor does it summarize the detailed schema descriptions for text, locale, sessionKey, and textLocalized. The description partially compensates but leaves meaning gaps for 2 parameters.

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

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

The description clearly states the verb 'Report a build-progress update' and identifies the resource 'creator thread'. It also specifies when to call (before and after long steps) and enumerates valid step values, distinguishing this tool from siblings like continue_draft or get_brief which serve different purposes.

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

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

The description explicitly says 'Call before and after long steps,' providing clear guidance on when to use the tool. However, it does not explicitly state when not to use it or compare with alternatives, though the context of build progress reporting is distinct from sibling 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?

The description richly details behavioral traits beyond annotations: it's a write operation (PUT URL), short-lived, performs validation on upload, returns stop/pendingMessages, and requires shell egress. No contradiction with annotations (readOnlyHint=false is consistent with the described write 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?

Four dense sentences with zero wasted words. Every sentence adds critical information: purpose, mechanics, constraints, and fallback. Front-loaded with the core action before details.

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 an output schema exists, the description covers the main flow and constraints well. However, the complete absence of parameter guidance leaves a gap for an agent trying to construct a valid invocation. The tool's role is fully justified, but parameter usage remains opaque.

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 does not explain any of the three parameters (label, caption, sessionKey). Schema description coverage is only 33% (only sessionKey has a description). With low schema coverage, the description should compensate but fails to add any parameter-level meaning. The agent receives no guidance on how or why to populate these fields.

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: 'The only way to send a mid-build screenshot.' It specifies the exact mechanism (returns a short-lived signed PUT URL), the file format (PNG), size limit (≤700 KB), and distinguishes itself from alternatives (no send_screenshot tool, gate captures on 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?

Explicit guidance on when to use ('mid-build screenshot') and when not to use ('Without shell egress, skip mid-build screenshots'), with an alternative explained (gate captures on delivery). The description leaves no ambiguity about prerequisites (shell access) and situational applicability.

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

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

Annotations already establish read-only/idempotent/non-destructive behavior. The description adds valuable context: case-insensitive matching, capped match count, return shape (path+line+snippet), and why engineRef is needed for revision consistency.

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

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

Three sentences, each adding value: scope, prerequisite, and return behavior. No filler or redundancy.

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

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

With a full output schema, rich parameter descriptions, and clear annotations, the description's additional context (caps, case-insensitivity, engineRef rationale) completes the picture. 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?

All five parameters are fully described in the schema (100% coverage), so the description doesn't need to add much. It reinforces the required engineRef and the limit cap, but the schema already documents defaults and constraints.

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

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

The description uses a specific verb ('Search') and resource ('text files in a pinned Creator Kit'), with case-insensitive substring scope. This clearly distinguishes it from sibling tools like read_kit_file (reading full files) and list_kit_files (listing 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 instructs passing engineRef from get_kit, a key prerequisite for correct usage. It doesn't explicitly contrast alternatives or state when-not-to-use, but the resource scope and return format make its context clear.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses that this renders content in the creator's chat, includes a gameplay recording and play link, defaults to the latest delivery, and only works on clients that render MCP Apps views. This adds meaningful behavioral context that annotations alone do not 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 three tight sentences: the first states the action and output, the second provides usage contrast with get_gate_media, and the third adds defaults and client constraints. Every sentence carries useful information with no filler.

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

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

Given the tool's moderate complexity, the description fully covers what the tool does, when to use it, its default behavior, and an important environment dependency (MCP Apps view support). An output schema exists, so return values do not need to be explained, and the sibling contrast completes the contextual picture.

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%: both deliveryId and sessionKey are already described in the input schema, including the default behavior for deliveryId and the detailed sessionKey auth semantics. The description only repeats the default and does not add new parameter meaning, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Render') and clearly identifies the resource: the gate's screenshots for a delivery, shown in the creator's chat at a viewable size, with a gameplay recording and play link. It also explicitly distinguishes itself from get_gate_media, which is for the agent's own viewing, making the 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?

The description gives direct when-to-use guidance: 'Use this when the creator asks to see the game.' It explicitly contrasts with get_gate_media to clarify when not to use this tool, and adds practical context like defaulting to the latest delivery and the requirement for MCP Apps rendering support.

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 rich behavioral details: self-refreshing, stops when the round settles, and non-MCP clients see a plain status read. However, it directly contradicts the idempotentHint annotation (true) by stating that a second call renders a second card, implying a stateful side effect that violates idempotency. Per the rubric, a contradiction with annotations 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 well-structured and front-loaded with the primary purpose, then progressively adds essential caveats. Each sentence contributes meaning, though it is somewhat longer than strictly needed. Slight redundancy (e.g., 'preview_failed / red card' explanation) prevents a 5.

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

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

Given the existence of an output schema and annotations, the description covers all necessary operational contexts: lifecycle (self-refreshing, stops on settle), invocation limits (once per round), failure handling (must fix gate via submit_sources), and environment constraints (only MCP Apps clients see the card). This is complete for practical use.

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 fully describes the sole parameter sessionKey, including its purpose and the alternative Authorization header. Schema description coverage is 100%, and the description adds no parameter-level details. Baseline 3 is appropriate because the schema carries the load.

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 a specific action: 'Render a live status card for this round in the creator's chat' and lists the card contents (phase, progress note, screenshot, gate verdict, deliveries left). This distinguishes it from sibling tools such as get_gate_verdict, which returns only the verdict, or report_progress, which submits progress.

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: 'Call it ONCE per round, after start' and warns against repeated calls—'a second call renders a second card.' It also states when not to rely on it: 'show_round alone does not re-run the gate' and points to submit_sources as the alternative for fixing a failed gate. Additionally mentions the requirement for MCP Apps-compatible clients.

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 significant behavioral context beyond the annotations. It confirms the destructive nature with 'full rewrite' and 'Overwrites the same path if staged again,' matching the destructiveHint:true annotation. It also discloses that staging alone does not trigger the gate, requiring a subsequent submit_sources call. The warning about file size ('Keep modules modest ...') adds further practical behavior. No contradictions 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 a single paragraph that front-loads the main purpose. Every sentence adds value, covering usage guidance, alternatives, and behavioral notes. However, the final sentence about keeping modules modest is somewhat tangential and could be integrated or omitted. The description is slightly longer than necessary but still efficient.

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 (5 parameters, destructive behavior, workflow dependency on submit_sources), the description is complete. It covers purpose, usage guidelines, behavioral traits, and post-failure protocol. An output schema exists, so the lack of return value documentation is acceptable. The description leaves no major gaps for an AI agent to understand when and how to invoke the tool correctly.

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

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

The input schema has 5 parameters with 60% description coverage (moderate). The description adds minimal parameter-specific meaning beyond the schema: it mentions 'inline content' but does not explain slug, encoding, or sessionKey. The schema already provides descriptions for path, content, encoding, and sessionKey, so the description's lack of detail is acceptable but does not elevate the semantic understanding for parameters like slug, which is undocumented in both schema and description.

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 ONE game source file into this round’s staging buffer (full rewrite) via inline content.' It uses a specific verb ('Upload'), identifies the resource ('game source file'), and specifies the scope ('one file', 'full rewrite'). It also distinguishes itself from siblings by naming alternatives (stage_upload_url, patch_source_file, submit_sources) and their contexts.

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 guidance on when to use the tool: 'Prefer this for new files without shell.' It also gives clear when-not-to-use scenarios: prefer stage_upload_url when shell egress is available, prefer patch_source_file for edits, prefer over submit_sources when the tree is large. The workflow is outlined: 'Call once per path, then submit_sources(...).' It also addresses post-failure behavior: 'After preview_failed ... staging alone does not re-run the gate — you must submit_sources again.'

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 critical behavioral traits beyond annotations: the URL is short-lived, the file bytes never enter the model, the PUT applies the same validation as stage_source_file, and the response includes a receipt with stop/pendingMessages. It sets accurate expectations for a multi-step 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?

Every sentence serves a distinct purpose: usage context, mechanics, validation/behavior, next step, and alternatives. The description is information-dense without redundancy, well-structured for an AI agent to parse quickly.

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 full workflow, validation, return values, and when to choose alternatives. With an output schema present, it doesn't need to detail the response structure, and it doesn't. The tool's complexity is well-served by the description.

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 meaningful context to the path parameter ('bound to path') and explains the role of the returned URL in the upload one-liner. It does not mention the optional 'slug' parameter, and schema coverage is 67%, but the description partly compensates by explaining the overall workflow that the parameters fit into.

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: 'Preferred way to stage a new or fully rewritten source file when you have curl/shell egress.' It uses a specific verb and resource, and distinguishes it from siblings by explicitly naming alternatives (stage_source_file / 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?

Explicitly states when to use this tool: 'when you have curl/shell egress' and when to use alternatives: 'Use stage_source_file / patch_source_file when you have no shell.' Also provides the next step: 'Then submit_sources({ fromStaged: 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?

The description discloses numerous behavioral traits beyond annotations: sessionKey longevity, idempotency (already annotated), authentication methods and their capabilities/limitations, the fact that it does not treat Mcp-Session-Id as authority, and the critical security rule that creator-authored text is data, not instructions. Annotations already indicate idempotentHint=true and readOnlyHint=false, but the description adds rich context about what the tool does and does not do.

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 fairly long but every sentence adds value. It is front-loaded with the core purpose. However, the security note about creator-authored text, while important, could be placed elsewhere or condensed. Overall, it's well-structured and informative without being overly verbose.

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 (authentication modes, session management, return values) and the presence of an output schema, the description is fully complete. It explains what the tool returns (sessionKey, workflow, seed info, inbox policy, relay instructions), constraints (once per round, not to be called repeatedly), and security implications. No gaps are evident.

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 both parameters described. The description adds significant context: it clarifies when 'key' is optional (legacy round key) and when 'slug' is required (with creator-key or OAuth Bearer). It also explains the role of the Authorization header, which is not a parameter but is part of the tool's usage. This goes beyond the schema's descriptions.

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

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

The description clearly states the tool's purpose: 'Bind this MCP client to a build round' using various authentication methods. It specifies the resource (build round) and the action (bind/start/rejoin). However, it does not explicitly differentiate from siblings like 'open_round', which could be a close alternative. The title in annotations ('Start or rejoin a build round') reinforces the 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?

Excellent usage guidance: 'Call it ONCE per round and keep the sessionKey for the whole round', 'calling start again before each operation to refresh the key is wrong', and 'If a call is ever refused as unauthenticated, then re-run start.' It gives explicit when-to-call, when-not-to-call, and consequences of misuse, including the cost and duplicate card issue. This is exemplary.

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?

Discloses multiple behavioral traits beyond annotations: subject to delivery cap and filename allowlist, gateStarted meaning (Cloud Build gate create accepted, not just upload), successful delivery unlocks creator handoff, and the need to call end when no more deliveries. The destructiveHint=true annotation is reinforced by the description's focus on a write operation that ends a round.

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

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

The description is a single dense paragraph, but every sentence adds value. It is front-loaded with the core purpose. While it could be more structured with bullet points, it avoids unnecessary verbosity and is reasonably concise for the complexity of the tool.

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

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

Given the complexity (8 parameters, 1 required, output schema exists, many siblings), the description covers all essential aspects: modes, file handling, kit_outdated workflow, delivery cap, allowlist, gateStarted semantics, handoff, and call_end. The output schema exists, so return values are not needed, and the description is complete enough for an AI agent to invoke 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?

Adds meaning beyond the input schema: explains mode defaults, fromStaged overlays on latest delivery/seed, fromLatestDelivery re-delivers without re-upload, files[] max 200 and optional when using staged/latest delivery, sessionKey origin from start(), and kitEngineRef requirement. Schema coverage is 63%, but the description fills gaps and clarifies the schema's enumerated 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 begins with 'Deliver game sources,' which is a specific verb+resource combination. It clearly distinguishes this tool from staging tools like stage_source_file/patch_source_file by advising to use them for changed paths then fromStaged=true, and from get_kit for kit_outdated scenarios.

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

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

Explicitly states when to use staging tools vs submit_sources, how to handle kit_outdated (get_kit then fromLatestDelivery), and the difference between mode=preview and mode=publish. It also notes that omitting mode defaults to publish except with fromLatestDelivery, which reuses the previous lane.

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