Pixly

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

Annotations already declare non-read-only, non-idempotent, non-destructive, open-world behavior. The description adds two useful facts beyond them: it is credit-free, and it returns synchronously ('Returns a finished image at once'), which tells the agent not to poll for a job. It stops short of stating whether repeated calls produce new artifacts, which the non-idempotent hint would make relevant.

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 densely packed sentence, front-loaded with the most decision-relevant token ('Free (no credits)') and closing with the output/timing statement. Every clause carries information, though the enumeration of examples and layout/aspect forms duplicates schema enums and could be tightened.

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 10 parameters, 100% schema coverage, an output schema present, and annotations covering the safety profile, the description supplies what structured fields cannot: the free-of-cost condition, the synchronous return, and the paired-photo premise. Nothing essential for correct invocation is missing; only explicit sibling routing is absent.

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 coverage is already 100%, the description adds genuine semantics beyond the schema: it declares the implicit requirement of a before/after pair of the same place (which 0-required-parameter schema does not enforce) and reiterates the label-language rule. The layout and aspect options it mentions ('side by side, stacked, or split by a line; original shape, square, 4:5 or 9:16') map to enum values already documented, so the added value sits mainly in the input-pairing constraint.

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 concrete verb and artifact: it produces 'one comparison image from a before and an after photo of the same place', backed by three concrete example pairs (empty room/staged, daylight/dusk, before/after restyle). It also names the output medium ('a finished image at once'), which implicitly separates it from the sibling before_after_reel. An agent can identify the resource and result type 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?

It gives rich when-to-use context in the form of scenario examples ('an empty room and its virtual staging', 'a daylight shot and its dusk version') and flags a cost condition ('Free (no credits)'). However, it never states when to choose this over alternatives like before_after_reel or day_to_night, nor any exclusions or prerequisites, so selection guidance is contextual rather than explicit.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false). The description adds genuinely useful context beyond them: both photos are required, credits are deducted from the Pixly balance, and that revealStyle is ignored when videoIntent=day_to_night. It does not mention persistence or job/async behaviour, but the annotation coverage lowers the burden.

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 core purpose in the first clause, then the requirement and the fallback workflow. The long tool-list sentence is dense but earns its place as actionable routing. Slightly heavy, but nothing is truly 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?

An output schema exists, so return values need no explanation, and the description covers inputs, cost, and the one-photo workaround. The only mild gap is durationSeconds, which has no described meaning in either the schema or the description, and no mention of synchronous vs. job-based completion for a paid video render.

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 89%, so the baseline is 3. The description adds meaning above the schema by clarifying the before/after position convention for day_to_night (Before = daylight, After = its dusk version) and by linking beforeImageUrl/afterImageUrl to the output of specific photo tools, which is not stated 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 (animate) and resource (a social-ready reveal reel from two photos), with concrete examples of the transformation (empty room → staged, renovation, daylight → Day to Night). This clearly distinguishes it from the sibling before_after_image (image vs. video) without needing 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?

Goes beyond stating what it does: it declares both photos are required and, for the one-photo case, names the exact alternative tools (virtual_staging, remove_furniture, day_to_night, restyle_room, makeover_exterior) and where to pass their output (afterImageUrl or beforeImageUrl). This is explicit when/how-to-chain guidance an agent can act on directly.

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 establish non-read-only, non-destructive behavior; the description usefully adds that it costs no credits, is fully automatic, caps at 1–5 photos per call, and reports when nothing is detected. It does not clarify that output is a new asset or how results relate to the source photo, which would matter for a non-idempotent 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?

Front-loads the key qualifier 'Free (no credits)' and packs cost, scope, and the failure-report behavior into one dense sentence with no filler. Slightly run-on but 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?

With an output schema present, return values need no explanation, and the description covers cost, batch size, detection targets, and the no-detection edge case. It leaves the style and listingId parameters unaddressed, a minor gap for a 5-parameter 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 only 40%, so the description must carry weight; it confirms the 1–5 batch limit and the faces/plates targets, but ignores the style (blur vs pixelate) enum behavior and the listingId placement semantics. Baseline 3 is appropriate given partial schema coverage.

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

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

States specific verbs (find and blur) and resources (people's faces, car licence plates) with the domain (property photos) and scenarios (street/exterior shots, open houses). This clearly separates it from siblings like watermark_photos or declutter_photo 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 clear context: use before photos are posted, for street and exterior shots and open houses. It does not name any alternative tool or state when not to use it (e.g., versus watermark_photos), so it stops short of 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?

Annotations already declare readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the write/non-repeatable nature is known. The description adds one genuinely useful non-annotation fact — that the call consumes credits from the user's Pixly balance — but says nothing about synchronous vs. job-based execution even though a get_job sibling exists.

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 that lead with the transformation and the key differentiator (single photo, no second frame), then append the cost note. No filler, though the parenthetical example list is slightly redundant with the enum.

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 output schema present, return values need no explanation, and the cost warning plus the single-image constraint cover most agent needs. The one real gap is execution model — whether the result is immediate or must be polled via get_job — for a tool annotated as non-idempotent and open-world.

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 format, direction, listingId, duration and the imageUrl/r2Path choice, making 3 the baseline. The description only echoes the camera-move family ("zoom, orbit, fly-through, crane up"), adding no syntax or constraint detail 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?

Specific verb+resource: turns one listing photo into a short cinematic video via a named camera move, with example moves matching the cameraMove enum. The phrase "No second frame needed" implicitly separates it from the before/after tools, but it never names or differentiates itself from the closest siblings photo_to_video and flythrough_video.

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 second frame needed" gives implied guidance that this is the single-image path versus the before/after siblings, and the durationSeconds text states when to pick 10 s ("only when the user asks for a longer video"). However, nothing tells the agent when to choose this over photo_to_video or flythrough_video, which is the actual ambiguity among siblings.

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, openWorldHint=false, idempotentHint=false, and destructiveHint=false. The description adds two useful facts beyond the annotations: the operation costs nothing, and the returned listingId must be threaded into later calls. It does not restate safety traits, which is appropriate, though it could clarify non-idempotency explicitly.

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

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

Four compact sentences, each earning its place: purpose, title handling, downstream linking, and cost. The most important guidance is front-loaded and there is 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?

There is no output schema, but the description covers the critical return value ('listingId') and how to use it. Combined with the single optional parameter and full schema coverage, an agent has everything needed to call this 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, but the description adds operational meaning: ask the user once for the property name, pass their words as title, and omit it if they skip. This is more than the schema's example and directly guides correct invocation.

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

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

The description states a specific verb and resource ('Create a property folder') and clarifies scope with examples ('a set of listing photos, a walkthrough'), distinguishing it from per-image sibling tools. An agent can immediately tell this is the container-setup step.

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

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

It explicitly says when to use it ('before work on a whole property'), how to handle the optional title (ask once; omit if skipped), and what to do next ('Pass the returned listingId to the tools'). This is a complete usage recipe with no inference required.

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 safety profile (non-destructive, non-idempotent, closed-world), so the description rightly spends its words on behavior the annotations can't convey: the PUT contract ('same Content-Type'), the 1-hour ticket expiry, and the r2Path hand-off. That is substantive operational context beyond the structured fields.

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 tight sentences, front-loaded with the purpose and the LOCAL constraint before the mechanics. Every clause carries information — no filler, no restatement of the title.

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 correctly compensates by naming the returned fields (uploadUrl, r2Path) and the full client workflow. Combined with the schema and annotations, 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?

Schema description coverage is 100%, so the schema already documents filename, sizeBytes, and contentType with enum values. The description adds only the Content-Type-must-match-PUT note and the existence of uploadUrl/r2Path; baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('Get a presigned upload URL') and immediately scopes it to 'a LOCAL image file — the one case a URL can't cover', which cleanly separates it from upload_image_from_url. An agent can pick this tool over its sibling 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?

It gives a clear when-to-use condition (local file, not a URL) and a downstream routing instruction ('pass the returned r2Path to a generation tool instead of imageUrl'). The alternative upload_image_from_url is implied by the URL contrast rather than named explicitly, which is the only gap.

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 safety profile (non-read-only, non-idempotent, non-destructive, open-world). The description adds genuinely useful context beyond them: the operation consumes credits from the user's Pixly balance, and the output preserves the building and camera angle. It does not state whether the source image is left intact or what happens on repeated calls, so it stops short of a 5.

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 transformation and its alias (virtual twilight), followed by the visual effects and then the credit cost. Two sentences with no filler; the em-dash effect list is dense but each item 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?

An output schema exists, so return values need not be explained, and annotations cover the mutation/safety profile. The description supplies the cost behavior and output constraints an agent needs to decide and call correctly; only the treatment of the original image and failure/credit-refund behavior are absent.

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 r2Path, imageUrl, and listingId are fully documented in the schema, including the either/or requirement. The description adds no parameter-level detail, which is the expected baseline when the schema carries the load.

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

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

States a specific transformation verb and resource: turn a daytime listing photo into an evening/dusk scene, with concrete visual outcomes (lights on, warm glow, dusk sky) and a preserved constraint (building and camera angle unchanged). It is clearly distinguishable in substance from siblings like replace_sky or reset_season, though it never names a sibling to route against.

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?

Implies the usage context (a daytime listing photo) but gives no explicit when-to-use/when-not-to-use and names no alternatives among the many photo-transformation siblings (replace_sky, reset_season, enhance_photo). The agent must infer the boundary itself.

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 disclose that this mutates state, is not idempotent, and is non-destructive; the description adds the material detail that it consumes credits from the user's Pixly balance, which annotations cannot express. It does not say whether repeated calls re-charge credits or what happens to untouched regions, so it stops short of 5.

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, zero waste: function and scope first, then the cost consequence. Nothing padded or repeated from structured fields.

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 so return values need no explanation, and the credit-cost caveat covers the main behavioral risk. A gentle note on credit exhaustion failure behavior is the only real 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% and all three parameters are documented there, including the r2Path/imageUrl alternative. The description adds no meaning 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?

Specific verb ('remove clutter, mess, and personal items') plus resource (a listing photo) with a stated scope constraint: keep room, furniture, and architecture intact. That constraint helps separate it from siblings like remove_furniture or restyle_room, though those tools are never named.

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?

Implied usage is clear from 'listing photo', but there is no explicit when-to-use or when-not guidance and no mention of the obvious alternatives (remove_furniture, edit_staged_photo, restyle_room) that an agent must choose between.

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

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

Beyond the annotations (readOnly=false, idempotent=false, destructive=false), the description discloses cost (free, no credits), that a validated result is returned in one shot, that invalid layouts return exactly what to fix with a retry instruction, and the versioning behaviour (a changed plan is saved as its own plan and the earlier one is kept). This is precisely the contextual detail the annotations cannot carry.

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 free/cost point and the core action are front-loaded, and the retry loop and versioning details follow logically. Sentence three and four are long compound constructions that could be split, but every sentence carries distinct information with no obvious 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 7-parameter creation tool with an output schema present, the description covers the action, the input-authoring model, the failure/retry contract, the save destination, and the update semantics. Return-value detail is correctly left to the output schema, and nothing an agent needs to invoke it 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 description coverage is 71% and the nested schema is already highly descriptive (wall-sharing rules, L-shape guidance, planId change semantics, units). The description restates the essentials ('every room as a rectangle in metres (or feet) plus doors and windows', 'the whole updated layout') without adding syntax or constraints the schema does not already state, so a 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?

States a specific verb + resource ('draw a clean 2D floor plan') and immediately clarifies the distinctive input model: the agent writes the layout itself rather than the tool deriving it from photos. The '2D' qualifier and 'Free (no credits)' framing implicitly separate it from photorealistic sibling renders like render_floor_plan.

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 clear when-to-use context: read the user's description, or work from their hand sketch or brochure plan. It also states the re-invocation rule ('To change a plan, call again with its planId'). It never explicitly names an alternative sibling (e.g. render_floor_plan) or states when not to use this tool, so it stops short of 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?

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), the description adds meaningful traits: the untouched regions are copied rather than regenerated (a non-idempotent, preservation-guaranteeing behavior), credit consumption from the user's Pixly balance, and that style is inferred from photo history. No rate-limit or failure-mode detail, but the annotations plus this context cover the important ground.

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?

Single well-structured block, front-loaded with the core behavioral guarantee, then input classes, examples, mask note, and cost. Dense but not padded; the parenthetical example list is long yet each example is a distinct use case an agent can pattern-match against.

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, so return values need no explanation, and all 9 parameters have rich schema descriptions. The description supplies the elements the schema cannot: the preservation guarantee, credit cost, and the broad domain of accepted inputs. A statement about failure modes or typical latency would complete it, but nothing essential 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%, including a detailed mask definition with white/black semantics, so the schema does the heavy lifting. The description adds only a light restatement ('Optional mask limits the change to a marked area') and does not mention r2Path/imageUrl alternatives, style, or listingId. Baseline 3 is appropriate.

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

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

The description states a specific verb+resource and a precise scope constraint: 'Change one thing in a photo and keep everything else exactly as it is — the parts the edit doesn't touch are copied from the photo, not redrawn.' It also enumerates the input classes (staged room, Pixly result, user's own picture) and concrete edits, so an agent can distinguish it from siblings like restyle_room or remove_furniture.

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 context is clear: it works on any photo, gives representative edits (swap sofa, recolour wall, remove car, change sign words), and notes the optional mask narrows the change. What is missing is routing against specific alternatives — nothing says when to prefer restyle_room, remove_furniture, replace_sky, or enhance_photo over this generic 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?

Beyond the annotations (readOnly=false, destructive=false, idempotent=false, openWorld=true), the description discloses two genuinely useful traits: it returns 3 variants rather than one, and it consumes Pixly credits, which matters because idempotentHint=false means retries are billable. It stops short of saying how many credits or whether each variant is a separate charge.

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, each load-bearing: purpose, output behavior, and cost. The primary action is front-loaded before the secondary facts.

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, so variant structure need not be spelled out, and annotations carry the safety profile. What the description supplies (variant count, credit cost) plus the schema's source-path guidance makes it adequate, though credit amount and output resolution remain unstated.

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 r2Path, imageUrl, and listingId are already fully documented in the schema, including the 'either/or' requirement for the image source. The description adds nothing about parameters, 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 ('turn an amateur listing photo into a finished, professional photo') and names the edit dimensions it covers (exposure, color, clarity), which separates it from siblings such as restyle_room, declutter_photo, or touch_up_exterior.

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 framing ('in one step', cost in credits), but the description never states when to choose this over the many sibling photo editors, nor any when-not condition. An agent must infer the fit from surrounding tool names.

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 non-read-only, non-destructive, non-idempotent, open-world. The description adds critical operational behavior: it returns a job to poll via get_job, takes a few minutes, and consumes Pixly credits.

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 output and input requirements in three tight sentences. Every sentence adds either process, workflow, or cost information; 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 an output schema and rich annotations, description only needs to cover the callable contract and follow-up. It supplies the async job and credit model, making the definition 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?

Schema description coverage is 100%, so baseline is 3. The description repeats the 2-4 walking-order constraint already in the photos schema and adds no syntax or format details for title, format, or listingId.

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 output (one continuous camera move through a home) and the input scope (2-4 room photos in walking order). The pairwise 3-second moves and stitching detail distinguish it from generic single-photo video siblings like photo_to_video or cinematic_motion.

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

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

Provides clear implied context: it is for 2-4 photos in walking order and requires polling get_job afterward. However, it never names alternatives or states when not to use it (e.g., vs photo_to_video), so guidance stops at implied 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?

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), the description discloses critical non-obvious behavior: the tool never charges anything itself, the agent cannot pay on the user's behalf, and credits land in seconds after payment. It also enumerates each plan with its price and credit allotment, which is behaviorally relevant for choosing arguments.

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 usage trigger and the core return value, then the branch logic and recovery steps. The inline plan/price enumeration is dense and slightly interrupts the flow, but it earns its place by letting the agent choose a plan without another lookup.

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 2-parameter, non-required-arg tool with no output schema, the description covers what is returned (a Stripe Checkout URL), what it does not do (charge), the two parameter regimes, and the post-payment verification loop. Nothing an agent needs to invoke it 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 description coverage is 100%, so the baseline is 3; the description nonetheless adds meaning by tying 'plan' to the subscription branch and 'topUpUsd' to the existing-plan branch, and by listing plan names with prices/credits. It does not restate the 10–500 USD bounds or default values, which the schema already covers.

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: it returns a Stripe Checkout URL for the user to pay through, and explicitly distinguishes itself from the sibling get_credit_balance (which is for verification, not payment). An agent can tell instantly that this is a billing/payment-link tool rather than one of the ~30 image-processing 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 trigger is stated up front: 'Use when a tool fails for lack of credits or a plan.' It then splits the two usage branches explicitly (no active plan = subscription, existing plan = one-time top-up) and gives a post-payment procedure (check get_credit_balance, then re-run the failed tool). This is explicit when-to-use guidance with a named follow-up alternative.

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 fully covered. The description adds that plan information is included in the response, which is genuinely new, but nothing about auth requirements or return shape.

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?

A single front-loaded sentence with no wasted words; the resource being returned is stated immediately.

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 is the only statement of what comes back, and it does name both balance and plan. Slightly thin on return format, but adequate for a trivial zero-argument read tool.

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

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

The tool takes zero parameters, so there is nothing for the description to document; baseline 4 applies. No parameter meaning is missing.

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 resource ('Pixly credit balance and plan') with an implied read verb. It is unambiguous and, given the siblings are all image-editing tools, naturally distinguishable as an account query, though it never explicitly contrasts itself with them.

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: an agent can infer it calls up account balance/plan info, but there is no explicit when-to-use, when-not-to-use, or prerequisite guidance (e.g., whether authentication is required or when to check balance relative to generation calls).

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, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds useful behavioral context beyond those annotations: expected video job duration (1-5 minutes) and polling cadence (a few seconds between calls).

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 tightly written sentences, purpose front-loaded, followed immediately by actionable polling and batch guidance. No filler text.

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

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

With an output schema present, return values need not be explained, and annotations cover the safety profile. The description covers purpose, polling timing, and batch usage; it omits edge cases like invalid or expired jobIds, but is otherwise complete for a simple status-check tool.

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

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

Schema description coverage is 100%, so the schema already documents both jobId and jobIds. The description's mention of passing jobIds for a plan's steps largely repeats the schema's own description ('Several job ids at once (a plan's steps)'), adding little new semantic detail. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Check a generation job's status and fetch result URLs when it's done.' It clearly distinguishes this status-checking tool from the many generation siblings (photo_to_video, virtual_staging, etc.) without needing to name them.

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 concrete usage context: poll with a few seconds between calls, video jobs take 1-5 minutes, and use jobIds for several jobs at once (a plan's steps). It lacks explicit when-not-to-use or named alternatives, but the operational guidance is clear enough to steer the agent.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior. The description adds context the annotations cannot carry: uploads must be added by the user at the web app, connectors cannot send bytes, and the r2Path is available here — genuinely useful workflow 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?

Two sentences, front-loaded with the core purpose before the uploads explanation. The second sentence is somewhat dense/run-on but every clause carries information an agent needs to handle local-file uploads.

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 tool with no output schema, the description covers the two list modes and the upload workflow, implying r2Path is returned. It omits pagination/limit behavior, but overall it gives enough 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?

Schema description coverage is 67%; the schema already documents 'type' and 'listingId'. The description reinforces the 'uploads' meaning and adds the 'newest first' ordering, but says nothing about the undocumented 'limit' parameter or its cap, so it does not fully compensate 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 the user's recent generations', or 'uploads' for source photos, 'newest first') so the agent knows exactly what is returned. It distinguishes the uploads mode from the generations mode, though it does not explicitly contrast with siblings like list_listings or view_pixly_photo.

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 a clear when-to-use condition for the 'uploads' type: 'the way in when the photo is a local file', because 'connectors cannot send bytes'. This routes the agent usefully, but it offers no exclusions or explicit alternatives when the agent should instead call list_listings or view_pixly_photo.

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 safety is covered. The description adds real value beyond them: it discloses the returned fields (id, title, photo and video counts) and explains the folder resource model (what a listing holds), which is meaningful context for a 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 sentences, front-loaded with the resource and its structure, then the usage trigger. The parenthetical definition is dense but informative, and no sentence is wasted.

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 zero-parameter read tool with no output schema, the description covers the resource, the fields returned, and when to call it. It is complete enough to invoke correctly, though it omits any mention of result ordering or how an empty folder set is represented.

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; the baseline for a parameterless tool 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 conveys a specific resource (the user's property folders / listings) and even defines what a listing contains (photos, staged versions, edits, videos, floor plan) plus the returned fields (id, title, photo/video counts). The listing verb is only implied by the noun phrase rather than stated, and no sibling such as list_library or create_listing is explicitly contrasted, so it is clear but not sibling-differentiating.

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 an explicit trigger: 'Use when the user names a property, or before work for one, so results land in its folder.' That is clear when-to-use context, but it names no alternatives or when-not-to-use conditions, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and openWorldHint=true, but the description adds genuinely non-structural context: credits are deducted from the user's Pixly balance, one run produces the full scheme, and the house, roof, driveway, sun direction and neighbours stay exactly as shot. This preservation guarantee and the credit cost are exactly the kind of behavioral detail 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 sentences, front-loaded with the core purpose, followed by the cost note. The long em-dash element list is dense but earns its place by defining the scheme's components. Minor trimming possible but well-structured overall.

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

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

With an output schema present, return values needn't be explained, and the rich 100%-covered schema plus annotations carry the structural load. The description supplies the invariants (what stays as shot) and the credit cost, so an agent has enough to call it correctly. It could be tighter on credit amount and failure modes.

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's enumeration of elements (planting, terrace, pool, pergola, fire pit, fence, lighting) loosely maps to the 'include' enum and it mentions 'a chosen style,' but it adds no syntax, defaults or format guidance beyond what the schema already documents thoroughly.

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 (design the garden of an exterior listing photo) with explicit scope: it builds a coherent whole scheme of planting, terrace/deck, pool, pergola, fire pit, fence and lighting in a chosen style. This clearly separates it from single-element siblings like replace_lawn, reset_season or touch_up_exterior without the agent needing to open another 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?

Usage is implied rather than stated: the description conveys that one run builds the whole scheme, but never says when to prefer this over replace_lawn, touch_up_exterior or edit_staged_photo, nor when a partial-element tool would be the better choice. The scope ('add' vs 'full') distinction that would help routing lives in the schema, not the description.

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 it's a non-idempotent, open-world, non-destructive write. The description adds genuinely new context beyond annotations: it consumes credits from the user's Pixly balance, and explains the end-frame landing behavior. It omits any async/job semantics (the get_job sibling suggests polling), which would have earned a 5.

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 core action ('Turn a start photo ... into a video') and stays reasonably tight. The kitchen orbit example is illustrative but slightly expendable; overall efficient with no wasted preamble.

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, so return values need no explanation, and all 11 params are fully documented in the schema. The description supplies the remaining gaps an agent needs: credit cost, the optional end-frame behavior, and the cameraMove-vs-prompt choice.

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 11 parameters including enum trade-offs (model time/sound differences, cameraMove, format). The description only paraphrases ('choose the model, length and sound') without adding format or syntax detail, so baseline 3 applies.

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

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

States a specific verb+resource: turn a start photo (and optionally an end photo) into a video. The end-frame mechanism description (camera lands exactly on the second image) is distinctive and clarifying. However, it never names the related siblings (cinematic_motion, flythrough_video, before_after_reel) to differentiate 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?

Gives implied usage: with an end photo you get a landing shot, otherwise pick a cameraMove or prompt. But there is no explicit 'when to use this vs cinematic_motion / flythrough_video' guidance, leaving the agent to infer routing among several video-generation siblings.

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 substantial behavior beyond the annotations: the first call is a dry-run that returns each step's cost, the total and a confirmationCode, the card shows one button, the second call starts only steps whose photo is ready, and dependent steps require re-calling with the same code once the earlier result completes. It also points to get_job for polling. This is exactly the rich context annotations alone 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?

The core purpose is front-loaded in the first sentence, followed by the two-phase protocol. Sentences are long and clause-heavy (em-dash lists, nested conditions), which makes it dense, but nearly every clause carries required protocol information so little is wasted.

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 an output schema existing, the description still explains what each phase returns (costs, total, confirmationCode, jobs), how dependent steps sequence, and the photo-vs-video scope. For a stateful two-call batch planner this covers everything an agent needs to 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?

Schema coverage is 100%, so the baseline is 3, and the description earns above it by giving operational meaning to confirmationCode (gates the run, reused to trigger dependent steps) and to the steps array as an ordered plan. The dry-run-then-confirm semantics of confirmationCode are the added value the schema alone does not spell out.

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 a specific verb+resource (plan photo edits across several listing photos) and states the key differentiator: one plan with one total and one confirmation rather than a confirm per photo. It also draws a clean boundary against video tools, so an agent can distinguish it from the single-step siblings like straighten_photo or enhance_photo.

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 call-timing rules: the first call runs nothing and returns costs plus a confirmationCode, and the second call (only confirmationCode) starts the steps. It also states the photos-only restriction. It stops short of naming the single-edit siblings as the alternative path, so the routing guidance is clear but not fully explicit about when to prefer them.

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 cover the mutation/safety profile (readOnly=false, destructive=false, non-idempotent). The description adds a genuinely useful behavioral fact beyond them: it consumes credits from the Pixly balance, which tells the agent this is a paid operation. It does not, however, note that re-runs would re-charge (non-idempotent).

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 no filler; the visual action is front-loaded and the billing note follows. 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?

With an output schema present, return values need no explanation, and the billing disclosure plus rich schema make the definition nearly complete for a 6-param tool. The one gap is the absence of any when-to-use / routing guidance among the many sibling image tools.

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 parameters are fully documented in the schema. The description only echoes the text parameter with examples (price, area, SOLD), adding no meaning beyond what is already there, 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?

Specific verb ("Place") plus a concrete resource ("photorealistic 3D monument sign with your exact text") applied to a defined input ("a photo of an empty plot"). This clearly separates it from sibling tools like watermark_photos, virtual_staging, or restyle_room.

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 the context (an empty-plot photo) but never states when to choose this tool over alternatives such as virtual_staging or edit_staged_photo, nor any prerequisites for the source image. Usage is inferable but not guided.

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 are thin on specifics (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), and the description fills the gap well: it discloses the default behavior (joinery also removed), what 'movable' preserves, that the floor extra applies only in 'fitted' mode, that doors always stay, and that the operation costs credits from the Pixly balance. This is meaningful behavioral context an agent cannot infer from 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 core purpose is front-loaded in the first clause, and each subsequent sentence adds a distinct fact (default behavior, movable mode, floor extra, doors, cost). The prose is dense with em-dashes and parentheticals, but no sentence is filler, so it stays reasonably tight for the amount of behavior being conveyed.

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, so return-value explanation is unnecessary. The description covers the mutation's scope, defaults, mode interaction, an extra option, invariants (doors, walls, camera), and the credit cost, which is everything an agent needs to invoke this photo-edit 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 schema already documents mode, extras, r2Path, imageUrl, and listingId in detail, including defaults. The description largely restates those semantics in prose (mode default, extras-only-with-fitted, doors stay), adding little beyond what the schema carries, 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?

States a specific verb and resource ('remove furniture from a photo') and defines the outcome precisely: emptying the room while rebuilding surfaces behind the removed objects and keeping architecture and camera angle identical. It explicitly distinguishes itself from a named sibling, declutter_photo ('Declutter is the opposite: it keeps the furniture'), so an agent can route correctly 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 clear use context ('the blank canvas for restaging', 'a full renovation strip-back') and names the opposite sibling (declutter) with the condition that separates them. It does not, however, mention other plausible alternatives such as restyle_room, virtual_staging, or edit_staged_photo, so routing is only partially covered.

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

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

Annotations only declare the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true). The description adds meaningful behavior beyond that: a preservation guarantee that rooms/walls/doors/windows are kept exactly as drawn, nothing is added, written dimensions are omitted, and that the call consumes Pixly credits. Return/pagination behavior is not described, but an output schema exists to cover that.

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 input-to-output transformation before the preservation constraint and cost note. Slightly long and partially duplicative of the schema's look enum text, but no sentence is wasted.

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

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

With an output schema present, return values need not be explained, and all four parameters are covered. The description supplies the important non-obvious context (layout is preserved, dimensions dropped, credits consumed, open-world rendering). Adding explicit sibling routing would complete 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 100%, so the schema already documents look, r2Path, imageUrl and listingId in detail. The description reinforces the enum's two output styles but adds no syntax or precedence detail beyond the schema (e.g. which of imageUrl/r2Path wins is left to the schema). Baseline 3 is correct when the schema carries the load.

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

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

States a specific transformation (a photo of a floor plan 6 a polished furnished 2D or 3D isometric plan) with concrete input examples (hand sketch, brochure photo, blueprint, screenshot). An agent can tell this renders an existing plan photo, which implicitly differs from draw_floor_plan, but the description never names or contrasts that sibling, so differentiation is only inferable.

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 context is implied by the input requirements ('a picture of any floor plan'), and the credit cost is stated, but there is no explicit when-to-use vs. when-not, and no routing to the obvious alternative (draw_floor_plan) or to upload paths for sourcing an image.

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 the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), and the description adds value beyond them: the credit cost against the Pixly balance and the concrete preservation boundary of what will not be altered. It does not note non-idempotency or auth/rate-limit behaviour, so not a 5.

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, both earning their place: the first front-loads the action and scope, the second the cost. No filler 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?

With an output schema present and full parameter descriptions, the description only needs to convey purpose, boundaries and cost, which it does. A brief pointer that either imageUrl or r2Path supplies the source, or that results can go into a listing, is unnecessary since the schema covers 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 100%, so all six parameters (lawn, shade, stripes, r2Path, imageUrl, listingId) are already documented in the schema. The description adds only the general notion of a lawn transformation, no extra parameter meaning. 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 (replace) and resource (lawn) plus the exact scope: patchy/brown/bare grass in an exterior listing photo, with explicit boundaries ('driveways, paths, beds and the house untouched'). This clearly distinguishes it from siblings like touch_up_exterior or makeover_exterior.

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 context ('exterior listing photo') implies when it applies, but there is no explicit when-to-use or when-not-to-use guidance relative to neighbours such as reset_season or touch_up_exterior. Nothing tells the agent how to choose this over adjacent exterior-editing 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?

Annotations only establish that this is a non-destructive write; the description adds the traits an agent actually needs: a 1–2 minute asynchronous runtime with a required get_job polling loop, and credit consumption from the user's Pixly balance. It also discloses what is preserved (building, trees, reflections), which the 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?

Three tight sentences, each earning its place: what it does, how long it takes and how to wait, and what it costs. The purpose is front-loaded ahead of the operational and billing details.

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

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

An output schema exists, so return values need no explanation, and the description fills the remaining gaps an agent needs for a 7-parameter async, credit-consuming tool: latency, polling protocol and cost.

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 every parameter including the enums, sunX/sunY semantics and the imageUrl/r2Path requirement. The description only indirectly touches parameters via 'matching the light', which loosely maps to the sun=auto behavior, 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?

States a specific verb and resource ('replace ... sky in an exterior listing photo') plus the exact input condition (grey, overcast or blown-out) and the preservation guarantee. It is clearly distinguishable from sibling tools such as day_to_night, reset_season and replace_lawn.

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 a clear triggering condition ('grey, overcast or blown-out sky in an exterior listing photo') and the operational follow-up ('poll get_job until it completes'). It does not name alternative tools (e.g. day_to_night) 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?

The description adds meaningful behavior beyond the annotations by disclosing that the operation costs credits from the user's Pixly balance and that structural elements stay fixed. The annotations already cover safety and open-world traits, so the remaining credit-cost disclosure is the main added value.

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 efficient sentences, front-loads the core transformation, and uses concrete examples without wasted wording. Every sentence contributes to understanding the tool's effect.

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 annotations, complete input schema descriptions, and presence of an output schema, the definition is largely complete. It covers the transformation scope and credit cost, though it could say more about processing behavior or how image sources are expected to be supplied.

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 parameter meaning is already well documented, including the season enum and image source fields. The description reinforces the preservation semantics and seasonal scope but does not add substantial new parameter guidance 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 states a specific transformation: photographing the same property in another season while preserving the house, driveway, paths, and camera angle. It is clearly distinct from a generic edit, though it does not explicitly name related siblings such as day_to_night or replace_lawn.

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 through examples like removing snow or moving a summer shot to autumn or winter, but there is no explicit when-to-use guidance or comparison with alternative photo tools. An agent can infer the seasonal use case, but must still decide between this and siblings on its own.

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 establish the mutation profile (readOnlyHint=false, destructiveHint=false, non-idempotent, open world), and the description adds two genuinely useful facts beyond them: the source photo's layout, fittings, windows and camera angle are preserved unchanged, and the call 'Costs credits from the user's Pixly balance.' That billing disclosure is exactly the kind of non-obvious side effect an agent needs and cannot get from structured fields, though there is no detail on failure or fallback behaviour at the description level.

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 front-loaded sentence naming the operation and its surface scope, followed by a short sentence on the preservation constraint and billing. The em-dash list is dense but each item maps to a real capability; no sentence is filler and nothing important is buried at the end.

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, so return values need no explanation, and the description covers operation scope, the invariants it preserves, and cost. It does not mention the source-photo requirement or the library/folder plumbing, but those are documented in the schema descriptions of imageUrl, r2Path and listingId, leaving the definition complete enough 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 description coverage is 100% and each of the eight parameters carries a detailed description (including the per-surface preset lists and fallback-to-auto rules), so the baseline is 3. The prose contributes only the notion of 'one or more surfaces,' which merely restates the `surfaces` array and adds no 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?

States a specific verb and resource ('give one or more surfaces of a room a new finish') and then enumerates the exact surfaces it can restyle — walls, floor, cabinets, bathroom tiles, furniture — which matches the schema's `surfaces` enum. The phrase 'of a room' plus 'the room's layout, fittings, windows and camera angle stay exactly as shot' separates it cleanly from exterior siblings such as makeover_exterior or replace_lawn.

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 rather than stated: an agent can infer this is the tool for changing finishes without moving furniture, and the preservation clause rules out layout edits. But it never names an alternative (virtual_staging, remove_furniture, makeover_exterior) or gives an explicit when/when-not condition, so routing between the many photo-edit siblings 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.

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), but the description adds material context beyond them: it is free/no credits, it crops the edges slightly (a real side effect of a non-destructive write), and it reports when no straightening was possible. That is behavior an agent could not infer from 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?

Front-loaded with the cost and the core action, and every clause (mechanism, side effect, ordering advice, edge case) earns its place. The heavy use of em-dash asides makes it slightly denser to parse than it needs to 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 an output schema present, return values need no explanation. For a 3-parameter tool with full schema coverage, the description covers cost, mechanism, side effects, sequencing, and the degenerate-input case — nothing an agent needs in order to call it 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 description coverage is 100%, so the schema already documents r2Path, imageUrl, and listingId in detail. The description adds no parameter syntax or format meaning, which is the baseline-3 case when the schema does the heavy lifting.

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

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

Specific verb+resource ("straighten a property photo") with the exact mechanism spelled out: leaning walls made vertical from converging verticals and a tilted horizon levelled. This clearly distinguishes it from siblings like enhance_photo, upscale_hd, or edit_staged_photo.

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?

"Best before staging or any other edit" gives real sequencing guidance that shapes how an agent orders its calls, and the edge-case clause ("says so when the photo is already straight") sets expectations. It stops short of naming an alternative or stating when not to use it, so it doesn't reach 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 cover the safe/non-destructive profile, and the description adds real value beyond them: the credit cost against the user's Pixly balance and the conservative behavioral guarantees ('each only where needed', 'the house unchanged'). It does not disclose asynchronous/job processing, which is a notable omission given the sibling get_job, but with a job-style output schema this is 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?

Two sentences with the action and scope front-loaded, then a short cost note. The enumeration of effects is informative rather than padding, and nothing is wasted.

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

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

With an output schema present and annotations covering safety, the description sufficiently covers what the tool does, its credit cost, and its conservative scope. The main missing piece is whether invocation is asynchronous/returns a job, which matters in a system with get_job polling.

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 schema already documents all four parameters including the 'fix' enum values and the imageUrl/r2Path relationship. The description adds no format, default, or precedence detail beyond what the schema states, so the baseline 3 is correct.

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 a specific verb (retouch) and resource (exterior listing photo) and enumerates the exact effects (sky, lawn, driveway, clutter removal), so the purpose is concrete. It never explicitly separates itself from overlapping siblings like replace_sky, replace_lawn, declutter_photo, or makeover_exterior, so an agent must infer that this is the combined one-click variant.

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 'one-click' and 'each only where needed' implies when this tool is preferred (a single combined pass rather than per-area tools), but there is no explicit when-to-use, no exclusions, and no named alternative. Usage is left to inference 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?

The annotations already declare the full safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=true). The description restates only the mutation itself and adds no behavioral context such as reversibility, permission requirements, or what happens to the old name. No credit for the annotation-only safety disclosure.

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

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

A single ten-word sentence, front-loaded with the action and resource followed immediately by the gating condition. No filler, no redundancy — 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 simple two-parameter tool with no output schema, the description covers what it does and when to invoke it, and annotations carry the safety profile. It does not address the surprising destructiveHint (why a rename is destructive, e.g. overwriting a name) or any success/failure outcome, leaving a modest 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 both parameters (title, listingId) are already documented in the schema. The description adds no syntax, format, or constraint meaning beyond what the schema provides, 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 states a specific verb ("Rename") and resource ("property folders"), which usefully overrides the misleadingly generic tool name update_listing. It is clearly distinguishable from create_listing (creates) and list_listings (reads), though it does not name those siblings explicitly.

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

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

"only when they ask" gives a concrete trigger condition (respond to an explicit user request) rather than leaving invocation context to inference. It offers no comparison to alternative tools such as create_listing or list_listings, but the when-to-use condition itself 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=false, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the call persists the image into Pixly ahead of time and the benefit is avoiding repeated fetches of the same URL. It still does not say what handle comes back or whether a repeat import of the same URL duplicates the asset (relevant given 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?

One sentence, front-loaded with the de-prioritization caveat, then the legitimate use case. No wasted clauses and nothing buried.

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 import tool with no output schema, the description conveys the side effect (import into Pixly), the precondition that generation tools don't need it, and the reuse rationale. The only real gap is the return value/asset handle, which the agent needs in order to actually reuse the import later.

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 itself documents the URL format and constraints (JPG/PNG/WebP, max 10 MB). The description adds nothing about the single `url` parameter, 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?

The description states a specific verb and resource ('import a photo into Pixly') and the title reinforces it. It is framed as a caveat-first note ('Rarely needed') rather than a direct purpose statement, and it does not name a specific sibling tool it replaces, only the general class 'generation 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?

Explicit when-not ('Rarely needed: generation tools take an imageUrl directly') paired with a concrete when-to-use ('reuse one URL across several tools without refetching it each time'). This is exactly the alternative-comparison guidance the dimension asks for.

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 non-destructive, non-idempotent, open-world behavior, so the bar is lower. The description adds real value beyond them: 'Nothing in the photo changes' (content preservation), the output size ceiling, and the credit-charging rule that draws down the user's Pixly balance.

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, front-loaded with the action, limits, and use cases before the cost model. Every clause carries information; no filler or repetition of the title.

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, so return values need not be explained. The description covers purpose, scale limits, non-destructiveness, and pricing, and the schema covers all three parameters, leaving little an agent needs to infer. Only the absence of any sibling routing keeps it from a 5.

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

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

Schema description coverage is 100%, with r2Path, imageUrl, and listingId all documented including the alternative-to relationship and folder placement behavior. The description reinforces r2Path's origin (list_library) but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (enlarge), resource (photo), hard limits (4x, 4096 px long edge), and intended use cases (print, MLS uploads, large screens). It is unmistakably distinguishable from most siblings by the upscale/print framing, though it never names the closest alternative (enhance_photo) to sharpen 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?

Gives clear context for when this is the right call (print, MLS uploads, large screens) and states the cost condition that governs the decision: free when passing an r2Path from list_library, 1 credit for the user's own photo. No explicit when-not or named alternative is offered, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint/idempotent/non-destructive, but the description adds real context beyond them: the return is a downscaled copy, video surfaces only its first frame, the call is free and changes nothing, and text derived from it must exclude Pixly branding. That is meaningful behavioral guidance not present in structured fields.

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 purpose in the first clause, then usage, then constraints. Efficient overall, though the trailing branding instruction ('no #Pixly, no made with Pixly') is a slight extension of scope for a viewer 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 burden and does so: it tells the agent the output is a small visible copy of the image (first frame for video). For a one-parameter read tool, nothing material 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%, and the id parameter is fully documented in the schema (job id, get_job/list_library source, upload:<r2Path> form). The description adds no parameter-specific detail, 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?

States a specific verb (look at/view) and resource (user's Pixly photos or videos), and clarifies the video edge case ('a video gives its first frame'). No sibling tool does viewing, so the agent can distinguish it immediately.

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 says when to use it: 'before writing anything about a Pixly result: a caption, a listing description, what changed.' It also supplies the forcing constraint ('You cannot see Pixly results otherwise'), which removes any ambiguity about whether the call is needed.

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 cover the safety profile (non-read-only, non-destructive, non-idempotent, open-world), and the description adds genuinely new behavioral context: HD and watermark-free output, and that the call consumes credits from the user's Pixly balance. It does not disclose latency, permission requirements, or what happens to an existing photo already in a folder.

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 core action, then scenario aliases, then output and cost facts; each fragment earns its place. The 'also the tool for...' clause is slightly redundant with the opening but carries routing 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?

An output schema exists, so return values need no explanation. For a credit-consuming, high-complexity generation tool, the description covers purpose, trigger scenarios, output quality, and cost, and the rich schema covers sourcing and routing parameters.

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

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

Schema description coverage is 100%, so every parameter (style enum guidance, r2Path/imageUrl sourcing, deprecated numImages/stagingQuality, customInstructions caveats) is already documented in the schema. The description adds no parameter meaning beyond that, so baseline 3 is correct.

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: 'furnish and style an empty (or badly furnished) room photo in a chosen interior design style', and adds routing phrases ('redesign this room', 'show this room in another style'). It is clear on its own, but it never names the sibling it is not — restyle_room and edit_staged_photo plausibly overlap with those phrasings, so an agent cannot fully disambiguate from the text alone.

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 clear usage context: use for empty or badly furnished rooms, and for redesign/restyle-in-another-style requests. However it offers no exclusions or named alternatives, so a request like 'restyle the staged room' leaves the agent guessing between this and restyle_room.

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 safety profile (non-read-only, non-destructive, non-idempotent, open-world), so the bar is lower. The description adds cost behavior ('Free (no credits)') and batching behavior ('Returns every marked photo at once'), which are not derivable from annotations. It still omits whether originals are modified versus a new copy produced.

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?

A single, tightly constructed sentence with the cost signal front-loaded ahead of the functional detail. Every clause carries information — mark content, placement, per-call limit, and return behavior — with no filler.

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

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

An output schema exists, so return-value detail is not required, though the description still notes batch return. For a 6-parameter tool with a nested photo array, it covers the core interaction well but leaves gaps around source-photo handling, size parameter intent, and auth requirements.

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 67%, above the 50% floor but well below the 80% baseline, so the schema does much of the work on r2Path/imageUrl/useLogo/listingId. The description only adds natural-language reinforcement for text (name, phone), position (corner or middle), and the 10-photo cap, without elaborating on defaults or the size/logos interplay.

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 ('put the agent's or agency's mark on listing photos') and enumerates the mark types (text name/phone, saved logo), so an agent immediately understands this overlays branding. It is clearly distinct from other image siblings like blur_faces_plates or plot_sign, which redact or add physical signage rather than apply an ownership watermark.

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 decision-relevant cue — 'Free (no credits)' — which helps an agent prefer this over credit-consuming siblings, and the 'up to 10 photos per call' hints at batching. However, it never states when to use this instead of alternatives, nor any prerequisites or exclusions, leaving usage to inference.

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