Shapesoda

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

Annotations already declare it is a non-read-only, non-idempotent, non-destructive operation. The description adds substantial behavioral context beyond that: the link is one-time, valid for 10 minutes, requires uploading via the returned curl command, and has an environment reachability constraint. This is rich and useful operational detail.

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 tightly written sentences front-load the tool action, then the upload workflow, then the environment restriction and alternative. Every sentence earns its place with no redundancy.

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

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

The description covers the full workflow (create link, upload with curl, pass upload_id to vectorize), the key constraint (10-minute validity), and the critical environment fallback to open_editor. With no output schema needed to explain return values, this is complete for correct invocation.

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

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

There is one optional parameter, filename, and schema description coverage is 100%, so the schema already documents it as 'Optional file name, for reference only.' The description does not add any syntax, format, or constraint details for filename, 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 a specific verb and resource: 'Creates a one-time upload link for a local image file.' It also distinguishes the tool from siblings by naming open_editor as the alternative for incompatible environments and vectorize as the next step, so an agent can route correctly.

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 conditions ('Only for agents whose terminal can reach shapesoda.com') and when-not-to-use conditions ('in Claude.ai and other chat apps the sandbox cannot upload there'), plus the exact fallback: 'call open_editor instead.' It also states the follow-up step of passing upload_id to vectorize.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds only the month-to-date scoping of the query but nothing about auth requirements, rate limits, or the fact that it's workspace/account-scoped.

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?

One sentence, front-loaded with the action and result, zero waste.

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-param read tool with full annotations and no output schema, the description is adequate to select it but does not explain the return shape or scope (e.g., which credits/plan). Minimum viable.

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?

Zero parameters, so baseline is 4. The description correctly indicates no filtering inputs are needed since it returns a fixed monthly summary.

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 result (credit usage this month and remaining balance), clearly distinguished from siblings like create_upload and vectorize which are unrelated operations.

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

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

The purpose implies when to use it (checking credit status), but there is no explicit when-to-use guidance or alternatives mentioned. Implied usage 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful behavior the annotations do not: it performs no vectorization itself and consumes no credits, plus describes the interactive hand-off flow. It stops short of noting any UI-state or auth prerequisites.

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

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

Front-loads the usage condition and follows with the behavior and the exclusion, so the agent gets routing info first. The opening sentence is somewhat run-on with its parenthetical, but every clause carries information and nothing is padding.

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 UI-opening tool with full annotation coverage and no output schema, the description supplies everything needed: when to call it, what it does not do, and the credit implication. Nothing required 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description correctly implies no arguments are supplied by the caller.

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 action (opens the Shapesoda window), the resource (the editor UI), and what the user does there (picks the file, sees the vector result, adjusts it). It explicitly distinguishes itself from the vectorize sibling by declaring 'Does not vectorize by itself,' so an agent can route 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 an explicit trigger condition ('when the user wants to vectorize an image but you cannot pass the image to vectorize'), enumerates the specific blocking cases (no image, upload_id, or exact base64 bytes), and names a negative case ('Do not use for generating new images'). The when and when-not are both spelled out.

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=false, destructiveHint=false and idempotentHint=false, so the mutation profile is covered. The description adds one genuine behavioral fact not in the annotations — the 24-hour free window — but omits whether the original result is kept or replaced, whether credits are charged afterward, and what auth the token grants.

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 the action and its required inputs front-loaded, and no filler beyond the marginally useful Shapesoda UI reference. 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?

An output schema exists and the parameter schema is fully documented, so return values and options do not need explanation here. For a non-idempotent, non-destructive re-run with ten parameters, the description is adequate but leaves the key lifecycle question (new result vs. overwrite) unaddressed.

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

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

Schema description coverage is 100%, so all ten parameters (colors, palette, corners, quality, min_area, image_type, smoothness, transparency, result_id, token) are already documented in the schema. The description only restates the origin of result_id/token and adds no syntax or defaulting detail, notably failing to say whether unspecified settings are inherited from the original vectorization.

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 ('Re-vectorizes a stored result') and names the required inputs, which implicitly distinguishes it from the sibling vectorize (this operates on an existing result_id rather than a fresh upload). The differentiation is implied rather than spelled out, and the trailing 'Used by the Shapesoda window' adds no selection value.

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 'free for 24 hours after the first vectorization' clause implies a usable time window after vectorize, which is useful context. However, it never explicitly says to prefer this over vectorize when a result_id already exists, nor what happens to the original result, leaving the when-to-use decision largely inferential.

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 destructiveHint=false, and the description adds substantial context beyond them: 1-credit cost across formats, mode=test free/watermarked, mode=preview free PNG whose link later buys vectors, per-format download links valid 24 hours or retention_days, and inline SVG when small. This is exactly the billing/retention/watermark behavior structured fields 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?

Front-loads the primary purpose, then input-selection rules, then return/cost behavior, with no filler sentences. It is dense and runs long, but the length is justified by a 43-parameter tool; splitting into clearer paragraphs would help slightly.

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 43 properties, 17 enums, nested objects, and an output schema, the description covers the genuinely ambiguous parts: which input channel to use, sibling routing, cost/mode semantics, and retention. Return values are already covered by the output schema, so nothing an agent needs to call this correctly 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 baseline is 3, but the description adds real meaning beyond the schema: the image input must be passed in 'exactly one way' among image, upload_id, or image_base64 (≤2 MB, only exact bytes already in hand) — a mutual-exclusivity constraint absent from the schema. It adds this constraint without duplicating the 43 documented parameters, so it earns above baseline.

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

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

States a specific verb and resource (convert raster image into vector), enumerates accepted input formats (PNG, JPEG, WebP, BMP, GIF, TIFF) and output formats (SVG, PDF, EPS, DXF, PNG), and explicitly contrasts with sibling open_editor. An agent can distinguish it from siblings 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?

Explicit when-to-use ('Use this when the user wants to convert...'), when-not ('Do not use for generating new images, editing photos or upscaling'), and a named alternative with its triggering condition (fall back to open_editor when no image input is available). Nothing is left to inference.

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