SpriteForge

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent, closed-world operation. The description adds that optional settings can be deferred, which is useful context, but says nothing about what is returned (a project id?) or that repeated calls create duplicate projects — the key consequence of idempotentHint=false for a creation tool with no output 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 short sentences, front-loaded with the action, with zero repetition or filler. Nothing could be removed 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?

For a low-complexity creation tool with full schema coverage and annotations covering safety, the essentials are present. The one meaningful omission is what the agent receives back and whether duplicate names are allowed, which matters because this is non-idempotent.

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 every parameter (name, light, style, outline, palette, description) is already documented with examples and formats. The description only restates that these are optional style settings; it adds no syntax or interaction detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a new SpriteForge project') plus the scope of the creation ('with optional style settings'). The explicit reference to update_project for later edits separates it from the mutating sibling without the agent having to compare schemas.

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?

'Only name is needed; the rest can be set later with update_project' is a concrete rule for when to supply optional fields versus deferring, and names the alternative tool. It stops short of stating exclusion cases (e.g., when to skip creation and use an existing project via list_projects/get_project), so not a 5.

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

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

The annotations already mark this as destructive and non-read-only, and the description adds important context: it spends the user's credits, refuses the job if priced above max_cents, saves output to the library, and typically takes 20 seconds to a few minutes. The request_id behavior is also explicitly described, which is more than the annotations convey.

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

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

The description is front-loaded with the core behavior and cost implications, then covers pricing approval, the max_cents guardrail, polling, and idempotency in compact sentences. Every sentence carries operational value.

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

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

For a complex 38-parameter generation tool with no output schema, the description covers the critical workflow, cost risk, required approval step, return value (job_id), polling path, and retry safety. The schema supplies the detailed mode-specific parameters, so nothing essential is missing.

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

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

Schema coverage is 100%, so all 38 parameters are documented structurally. The description still adds meaningful semantics for max_cents (use the quoted price or the user's budget, and the job is refused if the price exceeds it) and request_id (same id never starts or charges a second job), though it does not add much beyond the schema for the larger mode-specific parameters.

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

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

The description uses a specific verb and resource: 'Start an AI generation' for SpriteForge pixel art, and states that the result is saved into the user's library. It cleanly distinguishes itself from siblings by naming quote_generation and get_job as the pricing and polling 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?

It gives explicit when-to-use and sequencing guidance: quote_generation first unless the user already approved, then generate, then call get_job with the returned job_id. It also states the required max_cents guardrail and when to use request_id for safe retries.

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 readOnlyHint=true and openWorldHint=false annotations already establish the safety profile, and "Read-only" agrees with them rather than contradicting them. The description adds useful domain context beyond the annotations: credits pay for AI generation while hand-editing is free, which explains why an agent might inspect the balance. It does not disclose the exact response shape, but that is a modest gap for a zero-parameter read.

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

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

Three short sentences, front-loaded with what is returned and followed by the economically relevant distinction between paid generation and free hand-editing. No sentence is filler.

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

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

For a zero-parameter, read-only account lookup with no output schema, the description supplies enough for an agent to know what it will receive and when it is relevant. The only missing piece is rough units or format for "credits" and "storage," which would help an agent interpret the response rather than merely request 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 tool takes zero parameters, so the baseline of 4 applies; there is no parameter syntax an agent could get wrong. The description adds that the returned balance applies to the signed-in user, which is the only scoping fact that matters here.

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 names a specific resource (the signed-in user's SpriteForge account) and a specific payload (credit balance and library storage). No sibling tool retrieves account state, so the scope is unambiguous 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 phrase "signed-in user's" implies this targets the caller's own account rather than an arbitrary user, and no parameterized alternative exists among the siblings. However, there is no explicit when-to-use guidance, nor any statement of when this should be called versus checking credits via quote_generation.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description reinforces it with 'Read-only' and adds real value by disclosing the three data blocks returned. It doesn't describe caching, freshness of prices, or response shape beyond the enumeration, but for a fixed config read that's a minor gap.

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

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

Front-loaded with the payoff, then the imperative, then the mode — the ordering is right. The opening sentence is long and list-heavy, and the trailing 'Read-only' duplicates the annotation, but nothing is wasteful enough to cut.

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

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

With no output schema, the description carries the whole burden of telling the agent what comes back, and it does so concretely (tiers, prices, seconds at three sizes, nine generation types with limits, credit balance). Combined with a read-only annotation, an agent has everything needed to call it and use 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?

The tool takes zero parameters, so the baseline is 4 and there is no parameter semantics to explain. The description correctly implies no inputs are needed by framing it as a pure lookup.

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 (get) and resource (generation options), then enumerates exactly what's inside: quality tiers with price-per-call and typical seconds at 16/32/64px, the nine generation types and their limits, and credit balance. That enumeration lets an agent distinguish it from adjacent siblings like quote_generation, generate, or get_account without opening any 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?

'Call it before choosing a tier for the user' gives a clear triggering condition and placement in the workflow. It stops short of naming alternatives or exclusions (e.g. when to prefer quote_generation for a specific quote), so it's strong context without full routing guidance.

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

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

Adds real context beyond annotations: the wait window and default, the polling loop, the side effect of saving the result into the user's library (consistent with readOnlyHint=false), and automatic refund on failure. Missing only edge behavior such as invalid job_id or rate limits.

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 compact sentences, front-loaded with what the tool is, then timing behavior, then return values and failure refund. No filler.

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

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

With no output schema, the description carries the return contract itself (preview, new asset_id(s), png_url per sprite, sheet_url for animations/tilesets) plus the refund-on-failure rule, which is everything needed to call and interpret this tool.

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

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

Schema coverage is 50%; wait_seconds is documented in the schema and the description reinforces its default and polling purpose. job_id's provenance is only implied via 'started with generate', so the description partially but not fully compensates for the bare schema field.

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

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

States a specific verb+resource (status of a generation started with generate) and ties it directly to the producing sibling, so an agent can distinguish get_job from generate without opening either schema.

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

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

Gives explicit operational guidance: waits up to wait_seconds (default 25) and should be called again while still running, which tells the agent this is a polling tool. It does not name alternatives for retrieving finished assets (get_sprite_from_library, list_sprites), so it stops short 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?

The description discloses the return shape in useful detail — it tells the agent the response bundles settings AND sprites, which is behavioral information the schema does not carry. However, 'Read-only' merely restates the readOnlyHint annotation and adds nothing, and there is no mention of error behavior for a nonexistent project_id. Adequate but partly redundant 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?

Two very short sentences, front-loaded with the returned content. No waste, though the trailing 'Read-only.' sentence duplicates the annotation rather than earning its place.

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

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

For a simple single-parameter read tool with readOnlyHint/openWorldHint annotations and no output schema, the description does the important work of enumerating what is returned. The main omissions are project_id format and not-found behavior, which are minor at 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?

Schema description coverage is 0% for the single parameter, so the description carries the burden — yet it never explains the expected form of project_id (ID vs slug, where to obtain it). 'One project's settings' only weakly implies the parameter's role. With only one parameter the gap is small, but it is still unaddressed.

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?

Names the resource precisely and enumerates exactly what comes back: settings fields (name, style, description, light, outline, palette) plus sprites. The singular framing distinguishes it from list_projects, though the sibling is never named and the verb ('get') is only implied by the tool name.

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?

There is no statement of when to use this versus list_projects (all projects) or list_sprites (sprites elsewhere). The description does not say that the embedded sprites overlap with list_sprites, nor what prerequisites exist beyond a valid project_id. Only weak implied usage from the word 'One'.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so "Read-only" adds nothing. What does earn credit is behavioral context the annotations cannot express: the download links work without sign-in for 24 hours, so expiry/portability matters, and the description says how to fetch the file in a shell versus handing the URL to the user.

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?

Purpose is front-loaded in the first clause, and every sentence is actionable. It does run long as a single undifferentiated paragraph mixing return shape, URL parameter hacking, and shell mechanics, which makes the operational details harder to scan for a two-parameter read tool.

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

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

With no output schema, the description carries the return-value burden and does it well: it names the fields (preview, size, palette, png_url, sheet_url), explains the &frame/&scale/&cols modifiers, and covers the include_pixels extra. The only real hole is the unexplained asset_id, which the schema also leaves bare.

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

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

Schema coverage is 50%: include_pixels is documented in the schema and only echoed here ("palette-index grid"), while asset_id — the sole required parameter — is never described in either place, with no format, provenance (list_sprites/save_to_library), or failure behavior. The description had the burden of compensating for the gap and did not.

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

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

"Show one sprite from the user's SpriteForge library" gives a specific verb (show/fetch one) and resource (a single library sprite), and the singular framing distinguishes it from list_sprites. The description then enumerates exactly what comes back: preview image, size, palette, download links.

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

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

Usage is only implied: the singular "one sprite" plus a required asset_id signals this is for fetching a known asset, and the link-lifetime note implies it's for handing assets to the user. There is no explicit statement of when to prefer this over list_sprites or open_sprite_in_editor, and no guidance on what to do with an unknown asset_id.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful return context (style settings, sprite counts, most recently changed first) but repeats 'Read-only' and does not disclose pagination limits or whether all projects are returned.

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

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

The description is compact and front-loads the resource and returned fields. The final 'Read-only.' sentence is redundant with the readOnlyHint annotation but does not harm readability.

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 zero-parameter read tool with no output schema, the description gives enough detail about what is returned and in what order. It could mention pagination or whether the list is bounded, but the simplicity of the tool makes the current description largely sufficient.

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

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

The tool has zero parameters and 100% schema coverage, so parameter semantics are not applicable. The baseline for zero-parameter tools is 4.

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

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

The description clearly identifies the resource as the user's SpriteForge projects and specifies what each item contains (style settings and sprite counts). It does not explicitly contrast with sibling tools such as get_project or create_project, but the plural resource and listed attributes make the purpose recognizable.

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

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

Usage is implied by the listing semantics, but there is no explicit guidance on when to use this instead of get_project or update_project, and no stated exclusions. The agent must infer that this is the tool for enumerating projects.

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 'Read-only' sentence merely restates readOnlyHint=true, earning no credit. What does add value beyond annotations is the disclosed ordering ('most recently changed first') and the enumeration of returned fields, though pagination/limits are unstated.

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

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

Two short clauses, front-loaded with the resource and its returned fields, then the ordering and safety note. Nothing is wasted, though the parenthetical field list makes it slightly dense.

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

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

For a one-parameter read-only list tool with no output schema, the description covers what it returns, the ordering, and the scope. Missing only pagination/limit behavior and how to obtain project_id.

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?

One parameter at 0% schema description coverage. The description implies it must identify a single project, but never states the required project_id, its format, or where to obtain it (e.g., from list_projects). Partial compensation for the coverage 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?

States a specific verb and resource (list sprites) scoped to a single project, and even names the returned fields (names, ids, sizes, frame counts). It does not explicitly contrast with siblings, but none of them are sprite-listing tools, so ambiguity is low.

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

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

Usage is only implied by the phrase 'in one project' – an agent infers project_id scoping and that this is the way to enumerate sprites. No explicit when-to-use, when-not-to-use, or alternative is named (e.g., versus get_sprite_from_library or open_full_editor).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the useful internal-caller constraint, but it does not say what loading actually does (editor state mutation, what is returned or surfaced to the user), which is relevant for a UI-card operation.

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

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

Two short sentences with zero padding, and the core action is front-loaded. Nothing is wasted, though the second sentence could have carried some of the missing usage/parameter 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 one-parameter tool with no output schema, the description covers the action and caller restriction adequately, but leaves the caller unclear on what 'loading' produces and where a session_id comes from. An agent outside the card flow would not know whether calling this has any visible effect.

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 0% for the single parameter session_id, and the description adds nothing about what an edit session is, how its id is obtained, or whether it must be an active session. With no schema text to fall back on, this gap is not compensated.

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+resource: loads a sprite from an edit session into the SpriteForge editor card. It is reasonably distinguishable from siblings like open_sprite_in_editor or open_full_editor via the 'editor card' framing, but it never explicitly contrasts with those siblings, so an agent must infer the boundary.

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?

"Only the card calls it" is a meaningful restriction telling the agent this is internal/UI-driven rather than a general entry point, but it gives no positive condition for when an agent should invoke it and no routing to alternatives such as open_sprite_in_editor.

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 this is a non-readonly, non-idempotent, non-destructive operation, and the description adds real value on top: it returns an edit link alongside the interactive card, caps input at 128x128 pixels / 256 colours, and states that the user's edits persist to the edit session. The only gap is that it doesn't explain how the edit session itself is created or returned.

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 source-selection rule and return-link behavior are front-loaded and useful, but the long middle feature catalogue ("layers, selection and move, line/rectangle/ellipse, mirror painting, brush sizes, animation frames with onion skin and playback, palette tools") reads as marketing copy that adds little to tool selection.

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 an 8-parameter, no-required-args tool with nested `art` and no output schema, the description covers the input source options, hard limits, and what is returned (an edit link). It is nearly complete; only the relationship to the sibling editor tools is left out.

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%, so the baseline is 3; the description goes beyond it by framing the eight parameters as mutually exclusive source options with "none" meaning a blank canvas, which the schema alone does not convey. It also restates the size/colour limits that are only partly encoded 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?

Opens with a specific verb+resource ("Opens a sprite in SpriteForge's full pixel editor") and enumerates the capabilities that make it the *full* editor, which implicitly distinguishes it from the lighter `open_sprite_in_editor` sibling. However, it never names or contrasts with that sibling or `open_tileset_editor`, so an agent must infer the difference.

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?

"One source at most: session_id, asset_id, png_base64, art, or none for a blank width x height canvas" is an explicit, actionable selection rule that tells the agent exactly which input path to pick. It stops short of stating when to prefer this tool over `open_sprite_in_editor` or `load_art`, so it is clear context without exclusions.

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

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

Adds substantive behavior beyond annotations: edits go to an edit session rather than the library, save_to_library is required to persist, and the prior version is retained in history. This is exactly the kind of consequence disclosure annotations cannot carry. It stops short of covering failure modes or what the returned edit link contains.

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 tight sentences with the action and delivery mechanism front-loaded, and the critical persistence caveat immediately after. The parenthetical about inline vs. link is slightly dense but 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?

No output schema exists, and the description adequately explains what is returned (inline interactive card or an edit link) plus the session lifecycle. The main omission is the origin/format of asset_id, which leaves the agent without guidance on sourcing the sole required argument.

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

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

The single parameter asset_id has 0% schema description coverage, and the description never explains what an asset_id is or where to obtain one (e.g., from list_sprites). With low coverage the description should compensate, and it does not.

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

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

Specific verb+resource: opens a library sprite in the pixel editor for hand-editing. It distinguishes itself from siblings like get_sprite_from_library (retrieve) and open_full_editor (whole editor) by naming SpriteForge library sprites and the pixel editor.

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 for when the tool applies (hand-editing a library sprite) and describes the inline-vs-edit-link delivery. It also gives the follow-up workflow: call save_to_library with session_id when done. It does not explicitly contrast with open_full_editor or get_sprite_from_library, so 4 rather than 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?

The annotations mark this as non-read-only, non-destructive, and non-idempotent, and the description adds substantial behavioral detail beyond that: edits save to the edit session, kind with session_id preserves tiles and user edits, and editing a base texture re-derives edge tiles while keeping hand-drawn tiles. It also explains the interactive card and edit link return behavior, which matters for an editor-opening mutation tool.

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

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

The purpose is front-loaded, and the dense detail is justified by the tool's complexity and nine parameters. However, the description is a single long paragraph with many conditional clauses, which makes it harder to scan than a structured breakdown 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?

Given the high complexity, 100% schema coverage, and no output schema, the description is complete enough: it covers the editor modes, the new-set versus session behaviors, Wang derivation rules, PNG layout inference, and a summary of what the result reports. No critical calling behavior appears to be 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 carries the baseline parameter definitions. The description still adds real semantic value by explaining parameter combinations and conditional behavior, such as session_id plus kind changing a Wang preview, the valid new-set input combinations, and how png_base64 is inferred as strip, sheet, or texture when layout is absent.

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

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

The description states a specific verb and resource: opening a tileset in SpriteForge's tileset editor as an interactive card and returning an edit link. It distinguishes Wang autotile behavior from platformer tile-by-tile editing, and it contrasts session continuation with creating a new set, so an agent can separate it from the sprite-oriented sibling editors.

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 context for the main parameter modes: use session_id for an existing edit session, give kind with session_id to switch a Wang preview, and otherwise supply kind plus palette/tiles, palette/base, png_base64, or size to create a new set. It does not explicitly compare against sibling tools such as open_sprite_in_editor or open_full_editor, so it stops 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description is consistent ("Read-only"). It adds genuinely non-derivable behavior: that the price equals what `generate` will charge, that failed calls are refunded, and that it also returns balance, affordability, and typical duration — all useful for the agent's decision loop.

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, all front-loaded: what it does, what it returns, how to use it, and the read-only marker. Nothing repeats the schema and no sentence is filler.

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

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

With 36 parameters and no output schema, the description must carry the return-value burden — and it does, naming price, balance, affordability, and time. Combined with a fully documented schema, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100% across 36 params, so the schema carries the field-level detail and the baseline is 3. The description earns a bump by telling the agent the argument set mirrors `generate`, which removes the need to reason about whether the two tools accept different inputs.

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

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

States a specific verb+resource — price a generation without starting it — and immediately anchors it to the sibling `generate` by noting it takes the same arguments. An agent can distinguish quoting from generating without opening either schema.

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

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

Explicitly prescribes the workflow: show the user the price and wait for go-ahead before `generate`, with a stated exception (user already said to proceed without asking). Names the alternative tool and the condition that selects it.

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

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

Annotations already declare readOnly=false, idempotent=true, destructive=false, and closed-world. The description adds the important behavioral detail that the write target is the *edit session*, not permanent library storage, which shapes what an agent expects afterwards; it omits failure/overwrite behavior, which is a minor gap given the idempotent hint.

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 short sentences, no filler, with the action and the caller constraint front-loaded. Every clause carries information.

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

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

The tool has nested objects, a required opaque session id, and no output schema. The description explains the write target but leaves the session_id contract and the response/result of the save unstated, so an agent cannot fully predict the call's requirements or outcome.

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

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

Schema coverage is only 50%: the `art` object is well documented in the schema, but `session_id` is an undocumented bare string and the description says nothing about where it comes from or what it identifies. With low coverage the description needed to compensate and adds zero parameter meaning.

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

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

Specific verb and resource: saves the user's edits from the SpriteForge editor card into its edit session. It does not distinguish itself from sibling save_to_library or save_to_library-style operations, so the agent still has to infer which save path applies.

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?

"Only the card calls it" implicitly tells the agent this is an internal editor-driven write, which is useful context, but no explicit when-to-use/when-not or named alternative (e.g. save_to_library) is given. Usage is implied rather than stated.

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 a non-read-only, non-destructive, non-idempotent write, and the description adds real substance beyond them: library-origin sessions update in place with the prior version retained in history, other sessions create new sprites, and repeat saves update rather than duplicate. It omits permissions/auth requirements and what the call returns.

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 dense sentences, front-loaded with the action and scope, then the branching rules. No filler, though the parenthetical listing of session sources and defaults makes it slightly heavy for a four-parameter tool.

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

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

Covers the mutation semantics, overwrite/history behavior, and defaulting rules needed to call it correctly. With no output schema, the description does not say what comes back (e.g. the sprite id) or how the saved sprite is named, which leaves a small 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 coverage is 100%, so all four parameters are already documented. The description adds only the behavioral interaction (as_new overrides library-origin update; project_id defaults to the most recently used project), which largely restates the schema's default text.

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

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

Specific verb+resource: save the sprite from a SpriteForge edit session into the user's library. It names the session origins (open_editor, open_sprite_in_editor, pasted edit link), which distinguishes it from save_art / upload_sprite without needing those schemas.

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?

Clearly states when this applies (any session, with the library-origin case spelled out) and how as_new overrides that. It does not name sibling alternatives such as save_art or upload_sprite, so the agent must infer which tool handles non-session artwork.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description adds the crucial why: each field replaces the old value with no history, so prior values are unrecoverable, and it advises confirming wording with the user. That is exactly the extra context annotations cannot 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?

Two tight sentences with the field scope front-loaded and the lossy-replacement warning immediately after. Every clause carries information an agent needs before calling.

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 7-parameter mutation with no output schema, the description covers partial-update behavior, irreversibility, and the confirmation requirement, which is the essential picture. It doesn't say what the call returns (e.g., the updated project object), a minor gap given there is no output schema to fill 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?

Schema description coverage is 86%, so the schema already explains formats for style, outline, light and palette. The description reinforces the field list and adds the replacement semantics, but adds no format or syntax detail beyond what the schema documents. 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 leads with a specific verb ("Change") and resource ("a project") and enumerates every mutable field (name, style, description, light, outline, palette), so an agent knows exactly what capability this is. It doesn't explicitly name siblings like create_project or get_project, so differentiation is inferred from the verb rather than stated.

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?

"Only the fields you pass change" and "confirm wording with the user first" give clear operational guidance about partial updates and when caution is required. It stops short of explicit when-to-use/when-not guidance against alternatives such as create_project or get_project, which would have earned 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?

Goes beyond the annotations by disclosing processing rules the agent could not otherwise know: 128x128 and 256-colour limits, and that pixels under 50% alpha become transparent. It does not address duplicate behaviour, which matters because idempotentHint=false is declared but the description never says whether re-uploading the same image creates a second sprite.

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 dense sentences with the primary action and inputs front-loaded, and the fallback routing last. Every sentence carries new information; nothing restates the title or the annotations.

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

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

Covers a mutation tool with a nested-object parameter well, including constraints and the escape hatch for on-disk files. The remaining gap is the return value: with no output schema and no statement of what comes back, the agent must infer that an id or sprite is returned in order to chain into save_art or open_sprite_in_editor.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the PNG format/size/alpha constraints on png_base64 and the framing of art as 'palette + index grid you drafted'. It stops short of explaining the interaction between project_id defaulting and the 'most recently used' fallback already 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?

States a specific verb and resource ('Add an image to the user's SpriteForge library as a new sprite') and immediately names the two input modes. The third sentence names the sibling save_to_library and the condition that selects it, so an agent can distinguish the two without opening either schema.

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

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

Gives explicit alternatives and an exclusion: pass png_base64 or art, but for a file on disk 'don't paste base64' — upload via curl to the editor endpoint and then call save_to_library with the returned id. Both the when and the when-not are stated with the concrete substitute tool.

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