spriteship

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

The description discloses critical behavioral traits beyond annotations: it defaults to a cost preview (dryRun=true), returns only estimatedCredits and billing info, requires explicit user confirmation before spending, and mentions server rejection with 400 for missing pairs. It also explains the self-loop behavior for seamless tiles. Annotations only say openWorldHint=true and readOnlyHint=false, but the description adds substantial context about billing, dry-run flow, and error handling.

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 front-loaded: it starts with PAID (image-to-video) to set expectations immediately. It packs a lot of actionable guidance into a few sentences, and every sentence serves a purpose (cost, animation behavior, grid-specific instructions, user confirmation requirement, error handling, dry-run default, return type). It's slightly long but justifiably so.

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 9 parameters, no output schema, and only basic annotations, the description is remarkably complete: it explains the cost model, dry-run flow, grid vs single-image behavior, user confirmation necessity, error handling for missing pairs, and what the response contains ({ jobId }). It even provides specific examples of ambiguous requests like 'Animate the treasure box' to illustrate the need for clarification. This covers all key operational aspects.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics by explaining the dryRun argument's purpose (cost preview, show user estimatedCredits, then re-call with false), and the pairs argument's meaning for grid assets. It also clarifies the idempotencyKey usage for retries. However, some parameter details like videoModel and motionHint are not elaborated in the description beyond the schema.

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

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

The description clearly states what the tool does: 'Animate ANY asset type' with image-to-video, landing on the source asset, and preserving the still image. It distinguishes this from siblings like frame_animation, create_animation_from_pose, and revise_asset by emphasizing that it works on any asset type and is paid.

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: it tells the agent to ask the user which stages first, call get_asset to see tiles, and get explicit start/end before spending. It also gives exclusion guidance: 'do not satisfy it by defaulting to 0→last' and explains the 400 error for grid animate with no pairs. This is strong usage guidance with clear alternatives and prerequisites.

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 readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the bar is lower. The description adds genuinely fresh context: the call itself is free (FREE approval checkpoint) while resuming starts the paid dependent animation, and the server rechecks the live credit balance only at resumption time. This cost-shaped timing detail is not expressible 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?

Five sentences, each earning its place: FREE label, exact calling condition, user-facing workflow, no-op consequence of declining, and credit-order detail. The gate condition is front-loaded so an agent can reject invocation in one step, and there is no filler or restating of schema content.

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

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

The full human-in-the-loop workflow, the exact gating values, the no-op semantics, and the credit-timing behavior are all present, which is significant completeness for a tool with a nested 8-direction schema and no output schema. Slight gap: post-submission behavior on a failed live credit check or the return value of the approval identifier is unnamed, but nothing an agent needs to decide whether and how to call is missing.

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

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

Schema coverage is 100 percent, so the schema already documents every parameter, including the required 8-direction keys, ranges, and the primitive omit-to-keep semantics for poseScales. The description only restates the submission workflow (adjust the proposed frameIndices and poseScales, submit all eight) rather than adding new meaning, so the schema carries an appropriate baseline 3.

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

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

Specific verb plus resource: the tool approves directional poses by presenting the eight previewUrls and submitting all eight adjusted indices and scales. It is sharply distinguishable from the many downstream job tools, because the precondition trio (status, wizardPhase, directionalPoseReview) defines exactly what this checkpoint is.

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?

Use-only-when condition is explicit, referencing the exact get_job fields that must hold. The when-not is equally explicit: closing or declining means do not call this tool, and the description states the consequence, the job stays paused and no dependent credits are spent. Together this fully routes an agent on when invocation is permitted.

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

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

The description goes beyond the annotations by explaining important side effects: failed/incomplete provider work is refunded automatically, and for waiting-for-approval jobs, reusable 360 and pose charges are retained. This is genuinely useful behavioral context that annotations like destructiveHint:false do not capture. No contradiction between the description and annotations is present.

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 and front-loaded, beginning with the essence 'Abort a running job.' Every sentence adds information: cost, refund rules, approval-specific behavior, and usage guidance. There is no fluff or repetition.

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

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

For a single-parameter tool with no output schema and existing annotations, the description provides all needed context: the core action, the specific cancellation timing, refund behavior, charge retention specific cases, and a usage recommendation. An agent can invoke this tool correctly without further information.

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

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

The schema already provides a clear description for jobId ('Job id to cancel.'), and coverage is 100%. The description adds no extra semantic meaning for the parameter beyond the basic one, so the baseline score of 3 applies.

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

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

The description states the verb 'Abort' and the resource 'a running job', making the tool's purpose explicit. The wording distinguishes it from siblings like get_job or retry_job, since those do not abort a running generation. The phrase 'FREE' also adds a useful top-level qualifier.

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 a clear when-to-use condition: 'Use this when a generation is clearly going wrong rather than letting it run to completion.' This is explicit context, but it does not name a specific alternative tool such as retry_job, nor does it state when cancellation would be the wrong choice. That prevents a full score of 5.

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

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

Annotations already indicate non-read-only and non-destructive behavior. The description adds valuable context: it returns a jobId (asynchronous, requiring polling get_job), handles the __idle__ special case, scales the animation to match other animations, and exports to every engine. These details go beyond the annotations and set accurate expectations for the agent.

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 serving a distinct purpose: the first states the core functionality and differentiators, the second covers the __idle__ edge case, and the third explains the async return and polling. Information is front-loaded and every sentence earns its place.

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

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

There is no output schema, so the description properly explains the return value (jobId) and directs the agent to poll get_job. It also covers the __idle__ fallback and the scaling/export behavior, making the tool's workflow clear. For a moderate 5-parameter tool, this is sufficient.

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

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

Schema coverage is 100%, with all 5 parameters described in the schema. The description reinforces the special '__idle__' value for poseId but does not add new information about fps, newId, displayName, or characterId beyond what the schema already provides. 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 uses a specific verb ('Promote a pose') and clearly identifies the output as a 'real 1-frame animation (a still/idle)'. It distinguishes from siblings by emphasizing the pose-to-animation conversion and the scaling to match other animations, making the tool's purpose unmistakable.

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

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

The description states this is 'FREE, no AI', implying it is a lightweight alternative to AI-driven animation generation. It clearly explains the use case: converting a pose into a 1-frame animation that scales and exports. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of fully explicit 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 goes far beyond the annotations by disclosing that the call is PAID, that it defaults to a cost preview, that planToken invalidates on changed inputs, that fan-out creation returns one jobId, and that generated atlases are cut by logical foreground objects rather than trusted row geometry. None of this contradicts the annotations.

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

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

The description is long, but for 22 parameters and a two-phase dry-run flow the length is largely justified. It is front-loaded with the core create action and the paid side effect, then flows through workflow, defaults, required fields, and edge cases. Minor redundancy exists around the dryRun behavior and 'see dryRun', but the structure remains scannable.

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

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

With no output schema present, the description still covers the return shape, polling via get_job, subsequent get_asset usage, fan-out behavior, and terrain's regeneration constraint. It also exposes important validation warnings such as bgType mismatches and non-type-specific parameter restrictions, making it complete for a tool of this complexity.

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

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

Although the schema already provides 100% parameter coverage, the description adds high-value semantics on top: the planToken lifecycle, projectId's role in supplying gameType, per-asset-type default counts, square-filling rules, the background bgType legality rules, and idempotencyKey retry guidance.

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 precise verb-and-resource statement: 'Creates a NEW asset from a prompt in any of the six types.' It names the six asset types, distinguishes creation from revision/editing tools like revise_asset, and immediately signals the tool's scope.

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

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

It gives explicit workflow guidance: the dry run must be shown to the user, an explicit yes must be obtained, then a real call must reuse the same request plus planToken. It also explains when not to use it, such as terrain having no per-tile edit path, and clarifies the relationship to animate_asset and fix_asset_seams.

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

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

Goes well beyond the annotations, disclosing the dryRun cost-preview default, the legacy gridRows/gridCols behavior, the character-stored gameType controlling later animations, and the exact return shape { jobId, expectedCharacterCount }. No contradiction with annotations exists; the idempotency discussion is consistent with idempotentHint: false.

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 dense, containing no filler or redundancy; every sentence adds a critical operational fact. The structure front-loads cost and entry-point context, then covers the animation caveat, the grid quirk, return values, gameType behavior, and the dryRun default in a natural decision order.

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

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

For a complex paid mutation tool with no output schema, the description is unusually complete: it explains cost, prerequisites, return contract, polling via get_job, the dryRun flow, grid legacy behavior, and gameType inheritance semantics. The absent output schema is compensated for by describing exactly what the call returns.

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 already 100%, and the description adds extra meaning on top: gridRows/gridCols are a 'legacy trigger' for four variations, dryRun returns a specific cost quote object and executes nothing, isometric is an alias for topdown, and idempotencyKey reuse prevents double-dispatch on retries.

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

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

States a specific verb and resource, 'Generate a NEW character from a text prompt,' and clearly positions this as the entry point for creating characters. It distinguishes itself from animation siblings by saying 'IMAGE ONLY' and naming generate_character_animation and generate_character_turn as separate steps.

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, including 'call create_project first if the user has no project,' cost expectations ('PAID (~150 credits)'), and the instruction that animation is a separate explicit step. It also explains when to use topdown vs. other gameType values and how isometric maps to topdown.

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 FREE and SYNCHRONOUS execution (no jobId), the permanent nature of gameType, and the side effect of seeding a starter level map. These additions go well beyond the annotations (readOnlyHint=false, openWorldHint=true, etc.), which don't mention cost, sync/async, permanence, or map seeding.

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, front-loaded with critical FREE/SYNCHRONOUS information. Every sentence carries unique content: creation container, gameType impact, starter map seeding, and reuse guidance. 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?

For a 4-parameter create tool with no output schema, the description is thorough about prerequisites, side effects, and the key gameType constraint. It doesn't describe the return value, which is a minor omission, but the overall context is complete enough 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 coverage is 100%, so the baseline is 3. The description adds value by explaining why gameType matters—'is what decides how they are drawn and animated'—reinforcing its importance beyond the schema's enum listing. It does not add detail for name/style/description, but those are already well-documented 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 clearly states it 'creates the container everything else needs', specifying that characters and assets are created inside a project. It distinguishes from siblings by explaining that the project is the root resource and that gameType determines how resources are drawn and animated. Mentions the starter level map side effect as part of its 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?

Explicitly instructs to call list_projects first and reuse an existing project rather than making a near-duplicate. Also frames this tool as the prerequisite for creating characters and assets, clarifying when to use it. Notes SYNCHRONOUS behavior so the agent knows not to poll.

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, it reveals that the operation is synchronous and AI-free, that the original is untouched, and that it returns { jobId: null, animation }, so the agent should not poll. This is substantial behavioral context not present in the annotations.

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

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

The description is brief, front-loaded with the most important constraints, and every clause adds value—cost/sync/AI status, exact-copy semantics, original untouched, and response contract.

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 3-parameter tool with complete schema coverage, the description supplies the return shape, job behavior, side effects, and key constraints. It gives the agent enough to select and invoke the tool correctly without an output schema.

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

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

Schema description coverage is 100%, so the schema already documents characterId, animation, and newId. The description reinforces that the copy is made from the current saved animation and under a new slug, but adds little parameter-level meaning beyond that.

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

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

The description uses a specific verb and resource: 'Make an exact copy of the CURRENT saved animation under a new slug' and lists preserved properties. It clearly distinguishes duplication from generation or mirroring alternatives.

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

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

The description gives clear context: FREE, synchronous, no AI, exact duplication of the current saved animation. It also explicitly says not to poll a job, but does not name alternative tools or state when-not-to-use conditions.

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

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

Annotations already declare the operation as read-only, idempotent, and non-destructive. The description adds useful behavioral context by stating output is 'engine-ready map JSON' from 'SAVED level data' with custom fields baked in, clarifying the source and transformation. No contradictions found.

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

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

The description is two sentences, with the primary purpose stated first and the alternative tool mentioned second. Every word adds value, and there is 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?

For a simple export tool with only two parameters and full schema coverage, the description adequately conveys the output type (JSON), source data (SAVED level), included transformations (custom-field values baked in), and alternative use case (zip bundle). No output schema is needed, and the explanation covers the essential context.

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

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

Schema coverage is 100%, with clear parameter names and descriptions for mapId and engine. The description does not add parameter-level details, but since the schema already fully documents both parameters, the baseline score of 3 applies.

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

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

The description clearly states the tool produces 'Engine-ready map JSON' from saved level data with custom-field values baked in. It distinguishes itself from the sibling get_export_command, which handles the zip bundle, making the tool's specific purpose and resource 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 directs users to get_export_command for the zip bundle alternative, providing clear when-to-use guidance. It also implies the tool is for JSON-only exports, which aligns with its title and avoids confusion with sibling export-related 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 adds substantial behavioral context beyond the annotations: it discloses the credit cost (~100 credits), the fact that it makes one image-to-image call, that it produces a new current revision, that it defaults to a cost preview (dryRun), and that it returns a jobId requiring polling via get_job. These details are not in the annotations (readOnlyHint false, destructiveHint false, etc.) and are crucial for correct invocation and user communication.

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 yet information-dense. Each sentence serves a purpose: flagging the cost, stating the core action, pointing to the free pre-check, warning against unnecessary spending, describing the revision outcome, and explaining the dryRun default and return value. There is no fluff, and critical information is front-loaded with the cost warning.

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 paid, async tool with complexity around dryRun and idempotency, the description is remarkably complete. It covers prerequisites (get_asset check), cost, default behavior, return shape ({ jobId }), and next steps (poll get_job). The lack of an output schema is compensated by this explicit return description, and the tool's side effects are clearly stated.

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

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

The schema description coverage is 100%, so the baseline is 3. The description does not add significant parameter-level meaning beyond what the schema already provides for assetId, iterationId, dryRun, and idempotencyKey. It does reinforce the dryRun default and cost preview behavior, but that is already in the schema, so no additional value is added.

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: 'Make a texture tile seamlessly.' This is a specific verb+resource combination that immediately distinguishes it from sibling tools like revise_asset or reprocess_asset. It also provides critical context about being a paid image-to-image call, which further differentiates it from free inspection 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?

The description gives explicit usage guidance: check get_asset first, use the free seamMetric.pass verdict to avoid spending credits on cells that already tile, and do not spend on passing cells. It also instructs to use the dryRun argument to preview cost and get explicit user approval before the real call. This clearly tells the agent when to use this tool versus alternatives.

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

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

The description transparently discloses key behavioral aspects: it is free, uses no AI, no credits, no approval required. It explains how the animation is composited into a spritesheet and mentions the return behavior ('Returns a jobId — poll get_job'). This goes beyond annotations, which are sparse.

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: opens with the key differentiator (FREE, no AI), explains the mechanism, lists examples, gives usage guidance, and closes with the return value. Every sentence earns its place 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?

With no output schema, the description covers return value (jobId) and specifies how to poll. It also provides sufficient context for a 5-parameter tool, including prerequisites (tiles exist, grid asset) and destination (every engine). The alternative tool is named, making the context 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 parameters are already described. The description adds semantic value, particularly for frameIndices, explaining that repeats allow holding or ping-ponging a frame. It also reinforces assetId must be a grid asset, though this is in the schema as well.

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: animate a grid asset by using its tiles as frames. It uses specific verbs and resources, and explicitly differentiates from sibling animate_asset by mentioning 'Try this before animate_asset whenever the motion already exists across the tiles.'

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 usage guidance including when to prefer this tool over animate_asset, with concrete examples (coin flip, flickering torch, chest opening). Also states the condition 'whenever the motion already exists across the tiles', effectively telling when not to use it.

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

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

The description goes far beyond the annotations: it discloses that the operation is paid with credits multiplied per animation, that existing names are never replaced but get numeric suffixes, that a pipeline assignment token must be copied verbatim, that jobs pause at waiting_approval, and that operations return an animationQualityGate. Annotations say readOnlyHint=false and idempotentHint=false, and the description's side-effect-heavy behavior is consistent with those.

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

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

The description is extremely long, dense, and unstructured as one wall of text. It does front-load the most critical facts (paid, cost multiplier, distinction from still animation), but several points are repeated or could be compressed, such as the repeated override-only guidance and the long free-credit qualification paragraph. Every sentence is informative, but the sheer length hurts usability.

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

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

For a high-stakes paid, multi-step tool with no output schema, the description is remarkably complete: it covers cost preview and approval flow, naming behavior, error handling (PROMPT_TOO_LONG, ANIMATION_PIPELINE_ASSIGNMENT_EXPIRED), per-operation jobId handling, the quality gate, and the optional free-credit edge case. An agent has enough context to call it safely and 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?

Although schema description coverage is 100%, the description adds critical parameter meaning: dryRun defaults to a cost preview, animDurations and customAnims[*].duration are override-only with a 2s default, mirrorAnims are free flipped copies, animationPipelineAssignmentToken must be copied verbatim, and poseFirstFrameIds/poseLastFrameIds must use only status:done poses. This substantially enriches 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 the specific operation (generate character animations with genuine motion) and explicitly contrasts it with create_animation_from_pose ('not the 1-frame still') and generate_character_turn ('Do NOT call... merely to prepare an animation'). An agent can immediately distinguish this from siblings.

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 extensive when-to-use guidance: ask the user before spending, use dryRun first, show directionalPoseReview and call approve_directional_poses, use list_character_poses for stored pose endpoints, and avoid generate_character_turn for preparation. It also names the sibling create_animation_from_pose as the alternative producing a still.

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?

Since the annotations only signal readOnly=false, idempotent=false, destructive=false, the description carries the behavioral burden. It discloses the paid credit cost, the dry-run default, free retry semantics, the ENTITY_BUSY 409 when other jobs are running, the never-replaces naming convention, the return shape, and the directional-pose checkpoint edge case.

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

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

The description is dense and front-loads the important paid/dry-run caveat, and nearly every sentence adds necessary information. However, it is a long block of nested parentheticals and semicolons rather than structured guidance, making it harder to scan than it should be for an agent.

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

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

Despite having no output schema, the description covers the return shape, cost preview, errors, naming behavior, concurrent-job constraints, supported game types, and relationship to directional-pose review. This is complete enough for an agent to call the tool without external context.

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

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

The input schema already documents all five parameters at 100% coverage, so the baseline is 3. The description adds value by tying dryRun, idempotencyKey, seedPoseId, and discardPendingResult into the cost/recovery model, such as confirmation reviving the same job and exact failed retries being free. It does not repeat every parameter, but the additions are substantive.

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 concrete action and resource ('generate a 360 turn animation') and clearly explains the outcome: spinning the character so the sprite exists from every side. It also explicitly distinguishes itself from generate_character_animation's internal mid-walk rotation, so an agent can tell the two apart.

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 and when-not-to-use guidance: only topdown and isometric characters are supported, other game types error 400 TURN_NOT_SUPPORTED, and it warns not to call this as mandatory setup for every animation. It names the alternative generate_character_animation and points to get_job for polling.

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 enriches annotations substantially: it reveals paid usage, the dryRun default returning a cost quote, the actual execution flow, absence of jobId, and the need to poll. This goes far beyond the annotations (readOnlyHint=false, openWorldHint=true, etc.) and clearly discloses important behaviors.

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

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

The description is two sentences with high information density: paid status, generation purpose, dryRun default, return value, polling instruction. It is front-loaded and every phrase earns its place, with no redundant wording.

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

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

For a tool with 7 parameters, no output schema, and cost implications, the description thoroughly covers the essential workflow: cost preview, actual execution, return shape ({ poseId }), polling behavior, and idempotency retry guidance. Combined with the rich schema, it leaves no obvious 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 description coverage is 100%, and the schema already explains all parameters in detail, including dryRun, idempotencyKey, and referencePoseId. The tool description reiterates the dryRun behavior but doesn't add new parameter meaning beyond what the schema provides, 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 clearly states the tool 'Generate a new pose for a character from a text description' with a specific verb and resource. It distinguishes from sibling tools by emphasizing text-based pose generation and mentions the output format ({ poseId }).

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 strong usage context: explains the cost-preview default, the two-step dryRun flow, and instructs to poll list_character_poses for completion. However, it doesn't explicitly mention when not to use this tool or name specific alternatives, so it misses the full 'when-not' criterion.

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 the annotations: it is 'PAID but very cheap (one Gemini call)', 'SYNCHRONOUS', 'Stores NOTHING', and defaults to a cost preview. These are safety and cost implications not captured by readOnlyHint (false), openWorldHint (true), idempotentHint (false), or destructiveHint (false). The description significantly reduces the risk of an agent invoking it without understanding the paid, non-idempotent nature. 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 four sentences, each providing essential information: cost and synchronous behavior, output structure, storage side-effect, and dryRun default. It is front-loaded with the most critical differentiator (PAID) and avoids redundancy. Every sentence earns its place, and the structure makes the tool's unique aspects immediately visible.

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

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

Given the tool's complexity (7 parameters, no output schema, paid execution), the description is remarkably complete. It covers the cost model, synchronous response, lack of jobId, output fields, side effects (stores nothing), default dryRun behavior, and how to chain the output into create_project. The schema covers parameters thoroughly, and the description covers behavioral context, making it sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The tool description adds minimal parameter-specific meaning beyond the schema; it only briefly references the dryRun argument ('DEFAULTS TO A COST PREVIEW'), but the schema already provides a thorough explanation. The description clarifies how the output (not parameters) should be reused, which is useful but not directly about parameter semantics.

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

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

The description clearly states what the tool does: 'Turns a rough game idea into { aiVision, aiPromptGuidance, aiNegativeGuidance }' — a specific verb and resource. It differentiates from siblings like create_project by emphasizing it produces reusable prompt guidance, and from async tools by noting it is synchronous with no jobId. The title 'Generate a project creative brief' aligns with the description.

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 usage guidance: it tells the agent to 'feed the wording into create_project (description/style) and into your own prompts', directing when to use this tool as a precursor to project creation. It also instructs on the dryRun workflow: 'DEFAULTS TO A COST PREVIEW — see the dryRun argument', and clarifies that results come back synchronously, distinguishing it from sibling tools that require job polling.

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, openWorld, idempotent, and non-destructive behavior, and the description adds rich behavioral context around extraction.status, the grid-tiles presentation layer, legacy fallback, and background shape confirmation. This adds meaningful transparency about output semantics without contradicting the annotations.

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

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

The description is long, but every sentence carries decision-relevant detail for the states and shape of the returned asset. The information is well ordered by asset type and status, though the single large paragraph makes it harder to scan than structured bullets would.

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

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

For a read-oriented asset lookup with no output schema, the description does a strong job of explaining extraction status enums, grid tile semantics, legacy behavior, and background results. It still leaves some output concepts like typed animation projection explained only at a very terse level, which is a real but minor gap.

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

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

The schema already documents assetId with full coverage, including accepted forms. The description repeats the id-or-slug fact but adds no deeper syntax, format, or edge-case meaning beyond the existing 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?

Clearly states a singular 'asset' as the resource, marking this as the single-asset lookup tool among siblings like list_assets, get_character, and get_map. It also describes the full asset payload scope: revision iterations and animation projection.

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?

Tells the agent it accepts an asset id OR slug, making the invocation decision straightforward, and explicitly explains how seamMetric.pass informs whether fix_asset_seams is even needed. It does not explicitly set exclusion boundaries against list_assets, so it stops just short of full alternative routing.

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 extensively explains behavioral aspects: the animationQualityGate semantics, collision detection rules, normalization of bodies, and URL expiration. It also notes that the payload matches the in-app preview, ensuring consistency. These details go beyond the annotations and provide a thorough understanding of the tool's output behavior.

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

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

The description is overly long and repetitive, with redundant explanations about collision and normalization (e.g., 'Bodies are normalized...' appears once, but the point about not subtracting offsets is repeatedly stressed). The structure is a single dense paragraph, making it harder to scan. It could be significantly tightened without losing 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?

The description provides rich context for interpreting the returned data, including quality gates, collision handling, and URL expiry. It covers the main complexities of the payload. However, it does not address potential error conditions or what happens if the character does not exist, which might be relevant for a getter. Overall, it is fairly complete given the tool's purpose.

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

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

The only parameter, characterId, is described minimally as 'Character id.' The schema already provides the type and name, so the description adds little extra meaning. Since the parameter is straightforward, the baseline of 3 is appropriate.

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

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

The description clearly indicates that the tool returns the full PhaserCharacter JSON, including animations, poses, and other data. It is distinct from sibling getter tools by focusing on character-specific data. However, it does not explicitly state the action 'fetch' or 'retrieve', relying on the name 'get_character'.

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

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

The description implies usage by detailing the payload structure, but it does not explicitly compare with alternatives like get_asset or list_characters. It lacks clear guidance on when to choose this tool over others, though the focus on character specifics provides some hint.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: it clarifies that the files[] array is a logical canonical inventory, not an exact archive listing, and that this tool avoids downloading the zip. This is meaningful behavioral nuance that helps an agent interpret results correctly.

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 with no filler. The first sentence states the deliverable and the download behavior, the second explains usage and the key caveat with an alternative. Information is front-loaded and each sentence earns its place.

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

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

For a single-parameter read-only tool with rich annotations, the description fully covers what the tool returns, why to use it, and the important caveat about files[]. The absence of an output schema is mitigated by the description naming the manifest and JSON Schema. Nothing essential is missing for correct invocation.

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

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

The input schema covers the single parameter characterId with a simple description. With 100% schema description coverage, the description adds little beyond the schema, and none is strictly needed for this straightforward parameter. 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?

Description states exactly what the tool returns: the tizo-export.json manifest plus its JSON Schema, without downloading the zip. It explicitly frames the purpose as learning the Phaser integration shape and field meanings, and distinguishes itself from get_export_command for exact archive contents. This is a specific verb+resource with clear sibling differentiation.

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

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

The description gives direct usage guidance: use this to learn integration shape before wiring an export into a game project. It also names get_export_command as the alternative when exact shipped contents matter, and explains the files[] limitation. This is explicit when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds substantial behavioral context: resetsAt null/non-null semantics, firstAnimationAllowance eligibility rules, the 402/403 URL behaviors, and why the cap cannot be raised via API. No contradictions with annotations exist.

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 function and every subsequent sentence addresses a distinct operational decision. It is unusually long, but the length is justified by the tool's nuanced advisory role. Minor lack of structural formatting (e.g., bullets for the different walls) keeps it from a 5.

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

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

Despite having no output schema, the description tells the agent everything needed to call the tool and interpret results correctly: what fields are reported, what resetsAt means, how freeCreditLimit works, how to handle 402/403 responses, and how to advise users. Nothing critical for correct invocation or response interpretation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some contextual color—notably that ledger entries identify the consuming key and that includeLedger is optional—but it does not materially deepen the meaning of limit or apiKeyId beyond the schema's own descriptions. This meets, but does not clearly exceed, 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 first line, 'Current credit balance, and optionally the recent ledger,' clearly identifies the tool's verb-resource relationship and scope. It is the only sibling focused on credits/balance, so it is naturally distinguished from all other listed tools. The follow-up about ledger entries with apiKeyId/apiKeyName reinforces a unique purpose.

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

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

The description is explicit about when to use the tool: 'Check the balance before proposing any paid generation.' It also provides detailed conditional guidance for three distinct situations—balance shortfall, freeCreditLimit wall, and daily spend cap—and explicitly says what not to do ('Never suggest a purchase for a cap trip'). This is far beyond vague usage hints.

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, openWorldHint, idempotentHint, and destructiveHint. The description adds that definitions are read-only and that values are on get_map, which is useful behavioral context. However, beyond this definitions-vs-values distinction, it does not disclose much additional behavior not already covered by annotations.

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

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

The description is three sentences, all informative: what it returns, where values live, and how definitions are edited. No filler or redundancy, perfectly 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?

The tool is simple with two parameters, so the description covers the essential context (definitions vs. values, builtins, dashboard editing). Since there is no output schema, it could be more explicit about the response structure, but the high-level description is sufficient for this low-complexity 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%, and both parameters have descriptions. The description adds that kind selects 'character or asset' which aligns with the schema enum, but does not significantly deepen understanding beyond the schema. 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 clearly states it returns typed custom-field definitions for characters or assets, which is a specific verb+resource. It also distinguishes itself from siblings like get_map (which carries per-placement values) and get_character/get_asset (which likely return the full entity).

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 contrasts with get_map and mentions that definitions are edited in the dashboard. This gives clear when-to-use guidance and exclusions, though it does not explicitly say 'use this when you need definitions', but it's strongly implied.

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

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

Annotations already mark it read-only, open-world, idempotent, and non-destructive; the description adds meaningful behavioral context: it returns a command rather than file contents, requires the caller's shell to have SPRITESHIP_API_KEY, and describes engine-specific size behavior and canonical filenames. 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?

Three sentences with each earning its place: the core purpose, the critical shell-execution warning, the Phaser-specific sizing nuance, and the API key prerequisite. Information is front-loaded and there is 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 no output schema, the description clearly states what the tool returns (URL plus curl command) and the environment needed to use it. It is complete enough for an agent to know how to invoke it and what to do with the result.

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

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

Input schema covers all four parameters at 100% with descriptions, so the baseline applies. The description adds useful nuance about Phaser-only size options and canonical filenames, but does not need to compensate for schema gaps.

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

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

Description uses a specific verb and resource: builds an authenticated download URL plus a ready-to-run curl line for zip exports. It identifies the export types (character, asset, map) and the run-in-shell behavior, which distinguishes it from actual export/download 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?

Clear context: this is for obtaining a curl command to run outside the model, with an explicit warning that multi-MB zips must not be passed through the model. It states the API key prerequisite but does not explicitly name alternatives or when-not-to-use conditions.

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/openWorld/idempotent, so the description doesn't need to rehash safety. It adds valuable behavioral detail: output is presigned (URLs) and never inline base64, and the sheet is index-labeled. This goes beyond the structured annotations and helps set expectations about the response format.

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, front-loaded with the core output type, and each clause earns its place. The contrast between inline base64 and presigned URLs is a critical constraint stated in a single phrase, and the sheet usage guidance is concise but complete.

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

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

Despite 7 parameters and no output schema, the description covers the key behavioral aspects: output format, presigned URLs, sheet semantics, and integration with select_frames. The schema handles parameter details, so the description doesn't need to enumerate every field. It lacks some detail on how indices and size interact, but this is adequately covered by the schema. Overall, sufficiently complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds meaningful context around the format parameter (explaining the sheet's purpose) and the output nature (presigned), but doesn't materially enhance the understanding of other parameters beyond what the schema provides. 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 clearly states the tool's function: returning presigned per-frame thumbnails for character animations or asset motion pairs. It distinguishes itself from sibling tools by explicitly referencing select_frames as the intended downstream action, making its role in the workflow 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 explicit usage guidance: warns against inline base64, recommends format:"sheet" for judging whole captures, and names select_frames as the next step. This clarifies when to use this tool and how to choose between thumbnails and contact sheet, effectively covering both when and how.

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?

Despite readOnlyHint, idempotentHint, and openWorldHint annotations, the description adds critical behavioral detail: status:error enriches creditsRefunded, status:done for animation jobs requires get_character checks, queued:true means not started, and the credits block appears on terminal states. It also cautions about reporting net vs estimate. This far exceeds annotation-derived knowledge.

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 highly informative but very long, with multiple paragraphs and bolded emphasis. It is front-loaded with the core purpose, but the volume of detail (especially the credits reporting and animation gate sections) could be condensed. It is structured logically but not concise.

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

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

Given the tool's complexity (job polling, error enrichment, animation gates, credits reporting) and no output schema, the description covers every scenario an agent needs: queued, error, done, credits block, and follow-up actions. It leaves no ambiguity about expected behavior or required user communication.

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 jobId described as 'Job id.' The description does not add format or validation details, but it does explain that jobId originates from write tools and how polling interprets it. This adds contextual usage but not deeper parameter semantics. 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 clearly states the tool's purpose: 'Poll a background job.' It explicitly ties this tool to all write tools that return a jobId, distinguishing it from sibling getters like get_asset or get_character. The scope is unambiguous and well differentiated.

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 precise when-to-use instructions: 'Every write tool that returns a jobId is polled here.' It also specifies when to call get_character for animation jobs, when to report credits, and when not to attach purchase suggestions. This is explicit guidance on usage and alternatives.

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

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

Annotations already mark the tool as readOnly and idempotent; the description adds meaningful behavioral context beyond that, including the exact saved data components and the mapData:null return for unsaved maps. This goes beyond the safety profile provided by annotations.

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

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

Two crisp sentences: the first states the return payload, the second covers the unsaved edge case. No filler or unnecessary detail.

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

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

For a single-parameter get operation, the description adequately covers the return structure and the null case. It could have mentioned how to list available maps or error conditions, but those are minor given the simple schema and strong annotations.

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 mapId parameter is self-explanatory as 'Map id.' The description adds no additional parameter semantics, so the baseline score of 3 applies.

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

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

Description clearly identifies the tool as retrieving a map row with its saved level data, listing specific components (layers, placements, per-placement custom-field values). It distinguishes itself from sibling lookup tools like get_character or get_asset by specifying the map-specific payload and the mapData:null edge case.

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

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

No guidance is given on when to use get_map versus list_maps or other get_* tools. The description explains what the tool returns but not in which workflow it should be invoked.

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

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

The description goes beyond the readOnlyHint/idempotentHint annotations by disclosing the asynchronous generation after project creation, that the tool may return null, and that a re-fetch is needed. It also reveals the exact content payload (description, mount slots, assetSuggestions) which is not visible in the schema.

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

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

Two sentences efficiently convey the return value, the special assetSuggestions feature, and the async null case. No filler or redundancy; it is front-loaded with the core purpose and then gives actionable usage detail.

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

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

For a simple single-parameter read tool with rich annotations, the description fully explains the output shape, the async edge case, and how to use the returned assetSuggestions. No output schema exists, but the description compensates by clearly listing the returned fields and the null behavior.

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, projectId, is fully documented in the schema with 'Project id.' providing 100% coverage. The description adds no additional parameter-level guidance beyond what the schema offers, so the baseline score of 3 applies.

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

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

The description clearly states this returns a single project with specific fields (description, mount slots, assetSuggestions), using the verb 'get' implicitly via the tool name. It differentiates from sibling getters like get_asset and get_character by focusing on project-level data, and from list_projects by returning one project.

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

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

The description implies usage when you need a project's full details, and explicitly mentions re-fetching after creation because the result may be null asynchronously. However, it does not explicitly name alternatives like list_projects or contrast with other getters, but the context is clear enough for most cases.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered. The description adds genuinely useful behavioral context: hasAnimation is data-derived and cannot be inferred from the type, and Object's API type remains `static`. These are subtle correctness details that prevent an agent from making wrong assumptions.

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 dense sentences with no filler. The most important caveat (Object type mapping) is packed into the first sentence, and the animation warning is a single high-value sentence. Every clause earns its place.

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

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

For a read-only list operation with 100% schema coverage and 5 filtering parameters, the description is sufficient. No output schema exists, but the response fields are listed in the description (slug, hasAnimation, updatedAt, tags, favourite). An agent can call this correctly with zero additional information.

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

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

Schema description coverage is 100%, so the schema already fully documents all 5 parameters. The description reinforces the `static` vs Object naming and emphasizes that slug is an exact identifier, but these are clarifications of existing schema descriptions rather than new semantic value. 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 clearly states the resource (Assets) and enumerates the subtypes included, plus lists the available fields in the response. It distinguishes itself from sibling tools like get_asset and create_asset by being a list operation. The clarification that Object is now called Static Asset and the API type remains `static` is useful for agents.

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

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

The description implies this is used to list/search assets and the parameters provide filtering semantics. It doesn't explicitly name sibling tools to exclude, but the sibling context (get_asset, create_asset, revise_asset, etc.) combined with 'List' makes the usage context clear. Missing explicit 'when not to use' guidance, but the verb 'List' and filtering parameters establish 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?

The description reveals that pose generation has no job ID, making this the correct polling mechanism, and explains the meaning of the status fields (pending, done, error) and the stall condition. This goes beyond the annotations, which only declare read-only and 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?

The description is well-structured, with each sentence providing necessary context: field list, usage scenario, and stall warning. It is concise yet complete without any redundant or irrelevant 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 role in the generation workflow, the description covers all necessary aspects: field enumeration, status semantics, integration with generate_pose and generate_character_animation, and troubleshooting guidance for stalled poses. It is fully self-contained for a user to understand when and how to use it.

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

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

The only parameter, characterId, is described in the schema as 'Character id.' The description adds no further meaning or context for this parameter, so it does not enhance understanding beyond the schema. Since schema coverage is 100%, 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 lists all poses on a character, enumerates the returned fields, and explains its role as the poll target after generate_pose and source for generate_character_animation, distinguishing it from related tools.

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

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

It explicitly states when to use this tool: after generate_pose to poll for completion, and to fetch ready pose IDs for generate_character_animation. It also warns about interpreting 'pending long after pendingSince' as a stall, providing actionable guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context about contentVersion being an opaque change token that must not be parsed or ordered, plus a caching strategy. This goes beyond the annotations and enriches the agent's understanding of the tool's contract.

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

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

The description is two tight sentences: the first lists the returned re-sync signals, the second states the persistence strategy. No filler or repetition. Every phrase carries meaning, and the most important info (contentVersion handling) is front-loaded. This is an example of efficient, high-signal writing.

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

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

With no output schema, the description bears responsibility for explaining return values, and it does: contentVersion, hasActiveJob, apiReady, pose/animation counts, tags, favourite. It also provides the important re-fetch strategy. It doesn't explicitly state that the result is a list or cover pagination, but the limit parameter handles that. Overall, it is complete for a read-only list tool with good annotations.

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?

Input schema covers 100% of parameters with descriptions (name substring filter, limit with default/max, projectId restrict). The description adds no parameter-specific detail beyond what the schema provides, so the baseline of 3 applies. It does not mention parameters at all, but the schema is fully sufficient.

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 focuses on the re-sync signals returned for characters, which clearly implies this lists characters. The tool name and title explicitly say 'List characters', and the description distinguishes it from singular get_character by emphasizing the list with change tokens. However, the description lacks an explicit verb like 'lists' or 'returns', relying on 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 a clear usage pattern: 'Persist contentVersion per character and re-fetch only when it changes.' This tells the agent when to call the tool and how to use it efficiently. It does not explicitly mention alternatives like get_character for single-character retrieval, but the polling guidance is strong. There's no 'when not to use' exclusion, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond annotations by explaining the meaning of hasMapData:false (never saved, cannot be exported) and that maps include updatedAt, which helps an agent interpret the returned data. No contradictions.

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

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

The description is very short: two sentences with no unnecessary words. However, it starts awkwardly as a noun phrase rather than a verb phrase, which slightly reduces clarity. Still, it avoids fluff and front-loads the key fact that this is about maps.

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, no output schema), the description is reasonably complete but lacks an explicit statement that this tool returns a list/collection of maps. It does mention relevant response fields (updatedAt, hasMapData), but doesn't describe pagination or default behavior beyond what the parameter schema covers. The warning about hasMapData:false adds value but doesn't fully compensate for the missing 'list' framing.

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 both parameters (limit, projectId) have descriptions in the schema. The tool description adds no parameter-specific information, so it doesn't improve on the schema. Thus, 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 is a noun phrase describing map properties ('Level-editor maps with updatedAt and hasMapData') rather than stating the action of listing maps. It doesn't use a verb like 'list' or 'retrieve', and while the title provides that, the description itself is vague about purpose. It also doesn't explicitly distinguish from siblings like get_map or export_map.

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

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

No guidance is provided on when to use this tool vs alternatives. There's no mention of scrolling through maps, filtering, or that get_map might be more appropriate for a single map. The hasMapData note is about data semantics, not tool usage.

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

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

Annotations cover read-only, open-world, idempotent, and non-destructive behavior. The description adds important hidden semantics beyond those annotations: gameType is the project-wide default perspective at creation, while a character's stored gameType later governs its own animation and turn behavior. No contradictions with annotations are present.

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

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

Two compact sentences provide the full return shape and the key usage constraint without unnecessary filler. The most important facts about the default project gameType are front-loaded in the second sentence, just after the list definition.

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

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

For a simple list-only with one optional parameter and rich annotations, the description is nearly complete: output fields are listed and the critical gameType nuance is explained. The only missing element is explicit mention of pagination or truncation by the optional limit, but the schema already documents default 100 and max 500.

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?

There is only one parameter, limit, and the input schema already fully documents it with description, default, minimum, and maximum; schema parameter coverage is 100%. The description itself adds no parameter-specific meaning, so the baseline of 3 is appropriate.

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

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

The tool clearly returns all of the user's projects and explicitly lists the fields returned: id, name, gameType, style, itemCount, createdAt, updatedAt. This also differentiates it from sibling tools like get_project and list_assets by scoping the tool to the project resource set.

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

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

The description gives clear contextual guidance: it tells the agent to read project.gameType before generating anything because it is the default perspective for new content. It does not explicitly mention when to avoid this tool or name alternatives, but the sibling list and 'all projects' framing make the intended usage 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 (which already indicate non-idempotent and non-read-only), the description adds critical behavioral details: the flip is applied in-place, calling twice reverts the animation, frame count/order are preserved, and the return shape is { jobId, mirrored }. It also mentions cost ('FREE, no AI'), which is useful context not 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?

The description is front-loaded with the critical info ('FREE, no AI'), then explains the action, the idempotency gotcha, the frame preservation, the alternative, and the return value. Every sentence earns its place; nothing is wasted or 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?

Given the absence of an output schema, the description explicitly states the return object and polling mechanism. It also covers the non-idempotency hazard and the workflow for keeping both directions. This makes the tool fully understood without needing extra documentation.

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

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

The schema already documents both parameters with clear descriptions (animation slug, character id) at 100% coverage. The description adds context about the effect on the animation (in-place, frame preservation) but does not introduce new parameter-level semantics beyond the schema, 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 ('flip every cached frame') and names the resource ('ONE animation'), clearly distinguishing it from siblings like duplicate_animation. It also gives a concrete use case ('get walk_left from walk_right'), making the tool's purpose immediately 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?

The description explicitly warns about non-idempotency ('call it once and check the result before calling again') and provides an alternative for preserving both directions ('call duplicate_animation first and mirror the copy'). This is direct when-to-use and when-not-to-use guidance.

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

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

Annotations indicate non-destructive (destructiveHint=false) but description adds crucial behavior: 'the source animation is untouched,' 'FREE, no AI,' and async returns via job polling. It also discloses that frame windows index the FULL capture, which is an important caveat for correct use.

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 delivers value: purpose, classic example, proposal hint, indexing note, and return contract. It is front-loaded with the core action and remains compact despite covering multiple important nuances.

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 tool is async (returns jobId), has a non-trivial input (phase windows), and relies on external context (phaseProposal). The description covers all of this: how to get proposals, indexing semantics, output shape, and polling guidance. No significant gaps remain.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds meaningful semantics beyond schema: clarifies that frame windows are absolute indices into the FULL capture, and suggests phaseProposal as a verbatim source for the phases array. This elevates the 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 description states a specific verb+resource: 'Carve ONE multi-state clip into separate game-phase animations by frame windows.' It gives a concrete example (jump → crouch/rise/fall/land) and distinguishes this from other animation tools by emphasizing it splits one clip into multiple exportable animations.

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

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

The description clearly explains when to use this tool (multi-state clips needing game-phase separation) and provides the classic jump example. It even guides users to leverage phaseProposal from get_character. However, it doesn't explicitly mention alternatives or when not to use it, leaving room for minor ambiguity.

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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond that: Retry-After handling, the 100-entry cap, v1 lock-file upgrade behavior, and the explicit safety rule about not deleting local files without user confirmation. There is no clear contradiction with the annotations.

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

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

The description is long but information-dense. It front-loads the core purpose, then covers return types, upgrade behavior, limits, rate-limit handling, and safety. Each sentence contributes meaningful detail, though the dense single-paragraph structure is slightly harder to scan than bulleted guidance would be.

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

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

With no output schema, the description does a good job explaining what the tool returns: unchanged/changed/unavailable statuses, detailed summaries, and explicit actions. It also covers v1 upgrades, request limits, Retry-After, and deletion safety. It is less complete on how to populate the entities parameter and leaves terms like 'weighted sync budget' and 'review-removal actions' partially undefined, but overall it is strong for a complex planning 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 0%, so the description must compensate, but it never explicitly names or explains the 'entities' parameter structure. It indirectly references entity kinds and snapshot behavior, and mentions the 100-entry limit, but it does not explain required fields, the verbatim snapshot copy rule, or how to construct each entry. The schema has some nested descriptions, but the description itself leaves a significant gap.

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

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

The description uses a specific verb ('Compare') and names the exact resource ('assets/spriteship/spriteship.lock.json' vs current SpriteShip state). It clearly distinguishes itself from sibling get/list tools by emphasizing 'in one call' and by describing the unique statuses and actions it returns.

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

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

The description gives clear context for when to use this tool: to compare lock-file versions against current state and obtain a sync plan. It also covers the v1 upgrade path and request limits. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of a 5.

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

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

Beyond the annotations, it discloses that the operation is FREE and no-AI, that it cannot change art, that image-only characters return NO_ANIMATIONS_TO_REBUILD without creating a job, and that targeted rebuilds return an operationId/jobId to poll. This gives agents a strong behavioral model.

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 is reasonably sized, but it includes dense jargon like 'exact pose-owned scale references' and 'sibling-independent' that is unlikely to help an agent. Some sentences overlap with schema information and reduce conciseness.

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

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

Given the tool's complexity and lack of an output schema, the description covers the main use cases, response format, and an important edge case (image-only characters). It is not fully complete because it leaves some technical phrases vague and doesn't explain failure modes beyond the image-only case.

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% parameter description coverage, so the baseline is 3. The description adds some context around the animation parameter's optionality and full-character rebuild behavior, but it largely restates what the schema says and does not clarify parameter formats or constraints beyond that.

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

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

The description clearly identifies the tool as a repair/refresh tool that re-renders an animation from durable cached frames, with a specific verb and resource. It differentiates itself from art-generation siblings by explicitly stating it never re-generates art and only repacks/normalizes frames.

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 conditions: use it when a sheet looks stale or wrong after edits, or after a previous rebuild failed. It also states when not to use it (to change art) and how to distinguish targeted vs full-character rebuilds, though it does not name an alternative tool by name.

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

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

The description discloses important behavioral traits beyond annotations: the cost (~400 credits), the default to a cost preview via dryRun, that earlier takes are preserved (non-destructive), and that it returns a jobId to poll. This adds significant context beyond the readOnlyHint/idempotentHint/destructiveHint annotations and aligns with them (no contradiction).

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

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

The description is three sentences, starts with the critical cost warning, and packs in scope, preservation, default behavior, and return type without redundancy. Every sentence earns its place.

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

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

Given the tool has no output schema and seven parameters, the description covers the essential context: what it does, its non-destructive nature, cost, dryRun flow, and return value. Param details are in the schema, so the description is complete enough for an agent to select and invoke it correctly.

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

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

Input schema coverage is 100%, so each parameter is described. The description reinforces the dryRun default and idempotencyKey behavior but does not add substantial meaning beyond the schema's own parameter descriptions. Baseline 3 is appropriate because the schema already carries the burden.

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 re-runs video generation for a single motion pair of an animated asset, explicitly distinguishing it from regenerating all pairs. The verb 'Re-run' plus the resource 'motion pair' and the scope 'leaving its other pairs alone' make the purpose unambiguous and differentiate it from sibling tools like revise_asset or reprocess_asset.

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 conveys when to use this tool by focusing on a single pair and preserving other pairs, but it does not explicitly name alternative tools or provide exclusion criteria. It does give clear context, including the cost preview default and that earlier takes are preserved, which implies when this is appropriate.

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 indicate readOnly=false, destructiveHint=false, idempotentHint=false, which are consistent with the description's statement that the cleaner version is kept only if it measures better, and that it can never make the animation worse. The description goes beyond annotations by detailing the matteRepair stamp semantics, the conditional keep, the unchanged motion, the async pattern (returns { jobId } and poll get_job), and the source video expiration failure. This rich context is not redundant with annotations and enhances transparency. No contradiction.

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

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

The description is concise yet packed with valuable details: purpose, safety guarantee, retry behavior, failure mode, and return usage. It is front-loaded with the main action and condition. The opening 'FREE, no AI' may be slightly tangential but adds context about cost/technology. Overall, each sentence earns its place, though the density could be overwhelming for a quick scan.

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

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

Given that there is no output schema, the description compensates by clearly stating the return shape ({ jobId }) and the subsequent steps (poll get_job, re-read quality block). It also covers prerequisites (deliveredIssues containing 'matte'), the non-destructive conditional behavior, retry semantics, and the SOURCE_VIDEO_EXPIRED failure mode. This completes the tool's context for an async mutation operation, making it highly informative.

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 both parameters, with descriptions for 'animation' (Animation slug to re-matte in place) and 'characterId' (Character id). The tool description does not add significant parameter-specific meaning; it only mentions 'ONE animation's source video', which aligns with the existing schema. Given the high schema coverage, the baseline of 3 is appropriate, with no need for the description to compensate.

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 fixes edge artifacts (matte) on one animation's source video, specifically as a repair for quality read issues containing 'matte'. It distinguishes itself by targeting animation-specific quality defects and explicitly mentions the resource (animation) and the action (re-matte). This provides a specific verb+resource combination that sets it apart 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?

The description gives explicit when-to-use guidance: 'the repair for a quality read showing deliveredIssues containing "matte"' with examples (green fringe, flickering holes, ragged edges). It also provides an exclusion: if the same frames were already tried (matteRepair stamp), regenerate the animation instead. It further mentions the FREE and no-AI nature, as well as the SOURCE_VIDEO_EXPIRED failure, giving 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?

Annotations declare readOnlyHint=false and openWorldHint=true, but the description adds crucial behavioral context: the operation is synchronous and free, modern manifest revisions are never re-sliced, legacy paths retain source-sheet re-cutting, fitItemIndices is one-shot, omitted fields preserve current values, and cellOffsets:[]/cellInset:0 clear values. It also tells the agent to call get_asset afterwards. This goes well beyond the annotations and makes the side effects and return behavior clear.

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

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

The description is dense but every sentence earns its place: sync/free status, main operation, per-revision path differences, legacy prerequisites, field semantics, clearing semantics, and follow-up call. The most important operational facts (FREE, SYNCHRONOUS, no polling) are front-loaded. It is long, but the tool has real complexity to convey.

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

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

For a 6-parameter synchronous tool with no output schema, the description covers the operation, the revision-dependent behaviors, the legacy upgrade prerequisite, clearing semantics, and the recommended follow-up call. There is no obvious missing piece an agent would need to safely invoke it or interpret the flow.

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 params are already documented. The description adds meaning beyond the schema by explaining how parameters interact: anchor chooses the shared fixed point, cellOffsets apply per-item nudges, cellInset removes legacy separator bleed, fitItemIndices makes items fill their shared cell while preserving aspect ratio, and omitted fields keep current values. It doesn't enumerate every enum value, but the schema already does that.

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

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

The description states a specific verb+resource: 'Rebuild a staged, tileset, or terrain collection's presentation layout', and clearly differentiates itself from siblings like animate_asset, fix_asset_seams, or revise_asset by describing the layout/arrangement operation. It names the key dimensions (anchor, cellOffsets, cellInset, fitItemIndices) and distinguishes modern manifest revisions from legacy revisions, so an agent can identify the tool's unique role.

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

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

The description gives explicit when-to-use guidance: 'FREE and SYNCHRONOUS (no jobId — do not poll)', 'Legacy terrain must be upgraded to independent items first', and 'call get_asset afterwards for fresh presigned tile URLs'. It also states what not to expect (no AI) and how to clear fields, leaving little ambiguity about when this tool is appropriate.

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 thoroughly discloses behavior: FREE vs PAID based on recoverability, reuses paid results for succeeded work, defaults to a cost preview, returns { jobId } and mentions polling get_job. It also reveals the non-retryable error (400 JOB_NOT_RETRYABLE) and partially-committed state rationale. Annotations only provide readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false; the description adds extensive behavioral depth beyond these, including cost semantics and execution flow. No contradiction.

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

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

The description is longer than average but every sentence carries information. It is logically structured: cost model, purpose, reuse behavior, related tool, error condition, dryRun default, return type. Key facts are front-loaded (defines what it does and when it's cheap). It avoids fluff but is dense; a 4 reflects strong organization with slight density.

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 (cost variability, dryRun flow, idempotency, error handling), the description is remarkably complete. It covers when it's free/paid, what happens to succeeded work, how to get cost info via get_job, the non-retryable error case, the default dryRun behavior with user confirmation, and the return type. No output schema exists, but the return is described as { jobId } and dryRun returns a cost structure. No significant gaps for an agent to call correctly.

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

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

Schema coverage is 100%, each parameter has a description. The tool description adds valuable context: dryRun default true and its purpose (cost preview, requiring user confirmation), and idempotencyKey guidance for exactly-once dispatch on retryable errors. These enrich the schema descriptions without redundancy. Since the schema already covers the basics, a 4 is warranted for the additional operational guidance.

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

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

The description opens with a clear verb and resource: 'Re-runs the FAILED step of a job whose status is "error"'. It explains the tool reuses the existing job's prompt, model, and settings, distinguishing it from creating a new job. This makes the purpose specific and unambiguous, and it differentiates from siblings like cancel_job and create_* 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?

Explicitly states when to use: when a job is in error status. It names the alternative (creating the whole thing again) and explains why retry is preferred (cheap way out). It also instructs on the dryRun workflow: show cost quote, get explicit yes, then re-call with dryRun:false. Mentions get_job for retryMode/cost verification and idempotencyKey reuse for retry on specific errors. This is comprehensive guidance.

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

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

The description adds substantial behavioral context beyond the annotations: the 'PAID' flag, the two-phase cost-confirmation flow, 'never destructive' reinforcing destructiveHint=false, and the output contract '{ jobId } — poll get_job'. It also explains the idempotency semantics and that output assets land in get_job.assetIds. Nothing contradicts the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false are all consistent with the described behavior).

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

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

The description is one dense but efficient paragraph with no wasted sentences — every clause covers a distinct behavior (paid flag, additive revisions, terrain templateId, sourceItemIndex collection seeding, dry-run flow, return value). The most important fact ('PAID') is front-loaded, and the two-phase flow is stated before the return contract. Slightly long, but justified for a 10-parameter tool with a complex confirmation workflow.

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 paid tool with 10 parameters, two-phase dry-run flow, terrain-only options, and collection seeding, the description covers the full lifecycle: plan → token → real call → jobId → poll get_job. It mentions the cost preview and return shape. Minor gaps exist — exact error/retry handling beyond the schema note and the source of credits (get_credits sibling) — but nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 10 parameters — including a thorough dryRun explanation and planToken requirement. The description does add narrative flow (the seam between dryRun, planToken, and the real call, and the templateId category list), but these are auxiliary to what the schema already conveys. The baseline of 3 is correct since the schema carries 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 opens with a specific verb+resource pair ('Generate a new revision of an asset from feedback text') that clearly distinguishes this from create_asset (new asset), reprocess_asset (processing), fix_asset_seams (seam repair), and regen_asset_pair (regeneration). The 'revisions are additive, never destructive' clause pins down the semantic scope. An agent can differentiate it from the large sibling set without opening the schema.

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

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

The description provides clear conditional usage context: terrain assets 'also accept templateId', sourceItemIndex is described as seeding a related collection, and the dryRun→planToken→real-call workflow is spelled out step by step ('show the preview to the user, then resend the unchanged request with that token'). However, it never explicitly names alternatives or states when-not-to-use (e.g., 'use create_asset instead when starting from scratch'), so routing guidance is contextual rather than exclusionary.

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 annotations (which only indicate non-read-only, non-destructive, open-world), the description adds valuable behavioral detail: the full capture is retained (non-destructive), re-selection is possible, empty array resets, and it returns a jobId requiring polling via get_job. This gives the agent a clear mental model of the tool's behavior.

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

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

The description is five concise sentences, each providing distinct value: cost/aspect, core purpose, reset behavior, non-destructive guarantee, prerequisite workflow, and async pattern. It is front-loaded with the most critical information and contains no filler.

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

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

Despite having 6 parameters and no output schema, the description covers the essential workflow (get_frames first), the async job pattern, reset behavior, and non-destructive nature. The target variations are handled by the schema, so the description is complete enough for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, and the schema already documents the key param semantics (ordered frames, empty array reset, target types, etc.). The tool description repeats some of this but adds no new meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Curate') with a clear resource ('which frames an animation keeps'), and specifies the mechanism ('by index into the full capture, in order'). This clearly distinguishes it from sibling tools like frame_animation, which likely deals with creating/editing animation frames rather than selecting subsets.

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 usage context: 'Use get_frames with format:"sheet" first to choose indices' and explains the reset behavior via empty array. It also notes the non-destructive nature enabling re-selection. However, it does not explicitly name alternative tools or state when NOT to use this tool, so it falls just short of a 5.

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

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

Annotations provide basic hints (not read-only, not destructive, open-world), but the description adds substantial behavioral context: synchronous execution, no jobId, export-time resolution affecting already-placed tiles, and the null-to-clear behavior. This goes well beyond what annotations alone could 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 dense but every sentence earns its place: sync/free status, coordinate system, shape types, per-tile override, null clearing, export implications, and footprint distinction. It is front-loaded with the most decision-critical fact (synchronous, no poll) and avoids 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 complexity (nested collision shapes, coordinate normalization, per-tile semantics, export-time effects) and the absence of an output schema, the description is remarkably complete. It covers what the shape is, how to specify it, when it applies, and how to clear it, leaving the agent well-equipped 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 coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: normalized coordinates with origin top-left, circle radius as a fraction of width, tileIndex overriding the asset-level default, and null clearing the shape. This earns an extra point above 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 begins with a specific verb+resource: 'Author the PHYSICS shape a game should build its collider from for an asset revision' and clearly enumerates supported shapes (rect, circle, polygon). It also distinguishes the collision body from the FOOTPRINT, preventing confusion with related concepts.

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 usage context: it is FREE and SYNCHRONOUS, so agents should not poll for a jobId; it explains when to use tileIndex for per-tile overrides; and it clearly states the collision body is distinct from the FOOTPRINT, which has no physics meaning. However, it does not name any alternative tool explicitly, so it stops short of a full 5.

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

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

Beyond the annotations, the description reveals synchronous/no-job behavior, the effect on all later engine exports, and the legacy status of path_follow. It also documents that plain_image clears previous intent. None of this contradicts the readOnlyHint=false, destructiveHint=false 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 set of short, focused sentences with no filler. It front-loads the most critical call-shaping information—FREE and SYNCHRONOUS, no jobId—then covers purpose, allowed values, deprecation caveat, export effect, and tileIndex guidance efficiently.

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

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

For a synchronous mutation with five parameters, the description covers call mode, side effects, legacy handling, and conditional tile targeting. It does not enumerate per-intent config sub-fields or the exact success return, but the schema intentionally leaves config open and the tool has no output schema, so this is only a minor gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mostly restates what the schema already provides: the runtimeUse enum, path_follow's legacy status, plain_image clearing previous intent, and tileIndex targeting a tileset/staged asset. It does not add meaningful new parameter meaning beyond the schema.

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

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

The description opens with a specific verb and object: 'Declare how an asset revision should be rendered at runtime,' then enumerates the accepted render-intent modes. This clearly separates it from sibling asset tools like set_asset_collision_body and makes the tool's scope unambiguous.

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

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

It gives clear operational context, including that the call is synchronous and must not be polled, and that the intent flows into future engine exports. It also gives an explicit when-not for path_follow, directing users to author motion per placement in the level editor instead, though it does not contrast this tool with MCP 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 goes beyond annotations by disclosing cost ('PAID but very cheap'), synchronous behavior, return shape ('{ hint, cost } inline, no jobId'), dryRun semantics (returns a cost quote and executes nothing until dryRun:false), and idempotency key guidance. It also warns about 400 errors for non-staged assets. 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 four sentences, front-loaded with key facts (paid, synchronous, returns inline), then function, usage, and limitation. Every sentence adds value without 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?

The tool has moderate complexity (4 params, no output schema), but the description covers return values for both dryRun and real calls, execution model (synchronous, no jobId), cost protection rationale, idempotency handling, and asset type restriction. This is fully adequate for an agent to select and invoke the tool safely.

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?

Despite 100% schema coverage, the description enriches every parameter: explains 'pairs' as context only ('nothing is generated from them'), details dryRun's default true behavior and the required two-step consent flow, clarifies assetId is a staged asset id or slug, and gives idempotencyKey reuse instructions for retries. This goes well beyond the schema.

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

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

The description clearly identifies the tool as 'Suggest a motion hint for a staged asset' and explains its function: it reads a staged asset's prompt and stage pairs, then writes a one-sentence motion description to be passed as animate_asset's motionHint. This distinguishes it from siblings by focusing on hint generation rather than animation or asset creation.

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 when-to-use guidance is provided: 'Use it when you are about to spend ~400 credits on video and are unsure what to write.' It also gives a clear when-not: 'Staged assets only — any other type answers 400.' The relationship to animate_asset is stated, making the intended workflow clear.

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

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

Annotations already declare the tool as read-only, idempotent, open-world, and non-destructive. The description adds valuable context beyond that by explaining that it verifies the API key and that the scopes array indicates permissions. This complements 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 two sentences, front-loaded with the main action, and every word adds value. It efficiently communicates purpose, return value, and usage guidance without 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 the simplicity of the tool, the description fully covers what it does, what it returns, and when to use it. The explicit return object listing removes the need for an output schema, making the description complete within its context.

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

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

The tool has zero parameters, and the schema description coverage is 100%, so the description does not need to explain any parameters. The baseline of 4 is appropriate since there is nothing to add.

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 verifies the API key and reports its powers, using a specific verb and resource. It also lists the exact return fields (userId, username, keyId, keyName, scopes), making its purpose unmistakable and distinct from any sibling tool.

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

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

The description explicitly tells the agent when to call this tool first, specifically after a scope error, and explains how to use the returned scopes array to understand permissions. This is clear, actionable guidance with no ambiguity.

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