Pixly

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

The description adds a key behavioral detail beyond annotations: it costs credits from the user's Pixly balance. It also communicates that the result is a reel, but does not cover job lifecycle or failure behavior; annotations already handle readOnly/destructive hints.

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

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

Two sentences with no filler: purpose, use case examples, and cost are all included. The most important information is front-loaded.

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

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

The description is complete enough for a tool with a detailed schema and output schema: it conveys purpose, examples, and cost. It lacks alternative guidance and some parameter trade-off context, but those are secondary given the structured schema.

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

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

Schema description coverage is 63% and the description adds conceptual context by tying 'two photos' to the before/after inputs. However, it does not explain format, revealStyle, duration, or the R2-path vs URL alternatives beyond what the schema already provides.

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 action: animate a before→after transformation from two photos into a social-ready reveal reel. It gives concrete examples (empty room → staged, renovation) and the phrase 'before→after video' clearly distinguishes it from generic siblings like photo_to_video or virtual_staging.

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 implies usage through examples and the mention of a social-ready reel, but it never names alternatives or says when not to use this tool. With many sibling tools like photo_to_video, an agent would benefit from explicit 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 indicate the tool is not read-only and not destructive, but the description adds a significant behavioral detail beyond annotations: it costs credits from the user's Pixly balance. It also clarifies that no second frame is required, giving an important input-trait cue.

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

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

The description is two sentences with no filler. It front-loads the core purpose with the 'Photo to video:' framingcars, then adds two high-value details: no second frame needed and credit cost. Every sentence earns its place.

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

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

Input parameters are fully covered by the schema, and an output schema exists, so return-value details do not need to be in the description. The description supplies the essential non-schema context: single-photo input, cinematic camera moves, and the credit cost. It is complete enough, though it could have named a sibling like photo_to_video for even stronger routing.

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

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

Schema description coverage is 100%, so the schema already fully documents all six parameters with descriptions, enums, and defaults. The description's mention of camera moves like zoom, orbit, fly-through, and crane-up echoes the existing enum values without adding new semantic meaning beyond the schema.

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

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

The description states a specific verb and resource: turn a single listing photo into a short cinematic real estate video. It also distinguishes itself from sibling tools by specifying a professional camera move and explicitly noting 'No second frame needed', which separates it from before_after_reel and other video/photo tools.

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

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

The description provides clear context for when to use the tool: when the user wants a cinematic video from a single photo rather than a before/after comparison. It does not explicitly name sibling alternatives or state 'do not use when...', so it falls just short of a 5.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=false, destructiveHint=false), the description adds useful behavioral details: the ticket expires in 1 hour, the upload requires matching Content-Type, and the returned r2Path is used in place of imageUrl. No contradictions with annotations.

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

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

Three sentences, each earning its place: the local-file use case, the exact upload workflow, and the expiration caveat. The key differentiator (LOCAL) is front-loaded and the instructions are immediately actionable.

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 compensates by naming the critical return fields (uploadUrl, r2Path) and explaining how to use them. It also covers the lifecycle (1-hour expiry), the required PUT behavior, and the integration with generation tools—everything an agent needs to invoke the tool correctly.

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

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

Schema description coverage is 100%, so filename, sizeBytes, and contentType are already documented. The description reinforces the 'same Content-Type' requirement, which is helpful context for using contentType, but it doesn't add substantial meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Get a presigned upload URL for a LOCAL image file.' It also distinguishes it from the URL-upload sibling by calling out 'the one case a URL can't cover,' and names the relevant output fields (uploadUrl, r2Path) so an agent immediately knows what this tool produces.

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

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

The description provides explicit use context: this is for LOCAL files, not URLs, and it gives a step-by-step flow (PUT to uploadUrl with same Content-Type, then pass r2Path to a generation tool). It stops short of naming the sibling tool upload_image_from_url as the alternative, but the 'URL can't cover' phrase effectively routes 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 indicate this is not read-only and not destructive; the description adds valuable behavioral detail by disclosing that the operation costs credits from the user's Pixly balance. It also describes the visual transformation and clarifies invariants, though it does not specify whether the original file is replaced or a new file is produced, leaving some behavior to be inferred.

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

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

The description is a single well-organized sentence, front-loaded with the core transformation and followed by the essential credit-cost disclosure. The visual details are specific and useful rather than padded, making every phrase earn 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 transformation tool with an output schema, the description adequately covers what it does and that it costs credits. It does not explain the output/return flow or possible credit-ending failure modes, but the presence of an output schema reduces the need to document return values. The main gap is the lack of explicit sibling differentiation, which is a minor completeness gap given the tool's clear core purpose.

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

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

The schema already provides 100% schema description coverage for both r2Path and imageUrl, including the mutual-alternative relationship. The main description adds no new parameter-level meaning, so the baseline of 3 is appropriate; it relies on the schema for parameter semantics.

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

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

States a specific verb ('turn a daytime listing photo into') and a specific resource/result ('magazine-style evening scene — lights on, warm glow, dusk sky'). It also distinguishes the operation from siblings like replace_sky by noting that the building and camera angle are unchanged, making the tool's scope clear.

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

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

Provides clear context for when to use it: a daytime listing photo that should become a dusk/evening scene. It does not explicitly name alternatives or exclusions, but the intended scenario is unambiguous enough for an agent to select it over related photo-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 already indicate readOnlyHint=false and destructiveHint=false, so the description doesn't need to restate those. It adds valuable behavioral context: the operation consumes credits from the user's Pixly balance, and it preserves the room/furniture/architecture. This goes beyond the schema and annotations.

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

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

Two sentences with no filler. The core action and constraints are front-loaded, and the credit-cost note is a single useful addition. Every sentence earns its place.

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

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

The description is complete for a tool with a clear purpose, two well-documented parameters, and an output schema. It covers the key behavioral trait (credit cost) and the scope boundary. It doesn't mention what the output looks like, but the output schema exists, so that's not required. A minor gap is not stating when not to use it (e.g., for removing furniture), but the purpose clarity compensates.

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 parameters (r2Path and imageUrl) and their mutual exclusivity. The description adds no additional parameter-level detail, but the baseline of 3 is appropriate because the schema carries the full burden.

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

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

The description states a specific verb ('Remove') and resource ('clutter, mess, and personal items from a listing photo') and clearly distinguishes the tool from siblings like remove_furniture and restyle_room by specifying what is kept (room, furniture, architecture). This is a clear, non-tautological purpose.

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

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

The description implies when to use this tool: when a listing photo has clutter or personal items and the user wants them removed while preserving the room. It does not explicitly name alternatives or exclusions, but the scope is clear enough for an agent to select it over siblings. It also notes the credit cost, which is a usage consideration.

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 a key behavioral detail beyond annotations: 'Costs credits from the user's Pixly balance.' This is critical for an agent to inform the user about cost implications. The annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation aspect is covered. The description doesn't mention side effects like whether the original staged result is preserved, but the phrase 'preserving everything else' implies the edit is targeted. The credit cost disclosure is a strong addition.

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

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

Two sentences with no filler. The first sentence states the action, scope, and examples. The second sentence adds the critical cost warning. Every word earns its place, and the most important information (what it does, what it preserves) is front-loaded.

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

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

The tool has an output schema, so return values are covered. The description covers the core workflow (editing a previous staged result), the cost implication, and the preservation guarantee. It doesn't explicitly state prerequisites (e.g., must have a previous staged result from virtual_staging), but the parameter descriptions and the phrase 'previously staged photo' make this clear. The credit cost is a nice contextual addition. Minor gap: no mention of what happens if the edit fails or whether the original is kept, but the output schema likely covers the response.

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 six parameters. The description adds context by explaining the relationship between parameters (e.g., 'the same ids virtual_staging takes' for style, 'the resultUrls entry from its job' for imageUrl), but this is largely redundant with the schema descriptions. The description's main contribution is clarifying the overall workflow (edit a previous result), not adding per-parameter semantics. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: applying a specific change to a previously staged photo while preserving everything else. It gives concrete examples ('swap the sofa, add a rug') and distinguishes it from the initial staging process by referencing 'previously staged photo.' The title 'Edit Staged Result' reinforces this, and the description's verb 'Apply' plus resource 'previously staged photo' makes the purpose unambiguous.

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

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

The description implies when to use this tool: after a photo has been staged, when a user wants to modify a specific element. It doesn't explicitly name alternatives like virtual_staging or remove_furniture, but the phrase 'previously staged photo' and 'preserving everything else' clearly distinguishes it from initial staging or full transformations. The sibling list includes virtual_staging, which is the obvious alternative, but the description doesn't explicitly say 'use virtual_staging for initial staging' — that's 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?

With readOnlyHint=false and destructiveHint=false, the annotations already signal a non-read, non-destructive operation. The description adds valuable behavioral context by disclosing that it 'Costs credits from the user's Pixly balance' and 'Returns 3 variants to pick from,' which are not captured by annotations or 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 concise sentences front-load the purpose, then state the output format and cost. Every sentence adds information needed for correct invocation with 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?

Given the output schema exists and annotations cover safety, the description is nearly complete: it explains the core transformation, credit cost, and returns variants. It could mention that one of the two parameters must be supplied, but that is already implied in the schema descriptions and is not a critical 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 both parameters are individually described. The description adds no extra meaning about r2Path or imageUrl beyond the schema, so the schema carries the full burden and the description does not need to compensate.

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

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

The description clearly states the action ('turn an amateur listing photo into a finished, professional photo') and the specific enhancements (exposure, color, clarity). It distinguishes from siblings like upscale_hd or virtual_staging by describing generic finishing rather than a specific transformation, but it does not explicitly name any alternative.

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 'Real estate photo editing in one step' and 'amateur listing photo' gives implied context for when to use the tool. However, it does not explicitly state when not to use it or point to alternatives among the many sibling edit tools, so the agent must infer selection.

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

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

The description discloses key behaviors beyond the sparse annotations: 'this never charges anything by itself', 'you cannot pay for them', and credits arrive in seconds after payment. It also explains the state-dependent behavior (subscription vs. top-up), adding significant value beyond the readOnlyHint/destructiveHint flags.

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

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

The description is dense but every sentence earns its place: the usage trigger is front-loaded, then behavioral details and state-dependent logic are covered, and it ends with a clear follow-up. No filler or redundancy.

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

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

With no output schema, the description explains what is returned (a Stripe Checkout URL), the payment flow, the two state-dependent behaviors, and the recommended next steps. An agent has all necessary information 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?

Although the schema already has 100% coverage, the description adds critical meaning: plan pricing and credit counts, that the 'plan' parameter is ignored for top-ups, and that topUpUsd only applies to accounts with an existing plan. This exceeds what the schema alone provides.

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

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

The description clearly states the tool returns a Stripe Checkout URL and specifies the trigger condition ('when a tool fails for lack of credits or a plan'). It distinguishes itself from the sibling get_credit_balance by focusing on generating a payment link rather than checking balance.

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 the tool, defines behavior for both scenarios (no active plan vs. active plan), and provides a clear follow-up sequence ('check get_credit_balance, then run the tool again'). It also notes the agent cannot pay on the user's behalf, which is a critical usage constraint.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the useful context that the balance is 'current' and tied to the authenticated user, but does not disclose any additional behavior such as return format or potential errors. With annotations providing the main behavioral safety, a mid-range score is appropriate.

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

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

The description is a single clear sentence with no wasted words. It front-loads the key information (credit balance and plan) and avoids any redundant detail.

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

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

For a simple read-only tool with no parameters and no output schema, the description is sufficient for an agent to know what the tool does and when to call it. It could optionally mention that this is a read-only operation, but the annotations already convey that. The only minor gap is not specifying the exact response fields, but that is not essential given the title and description.

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

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

The tool has zero parameters, so there are no parameter semantics to document. The baseline for a no-parameter tool is 4, and the description appropriately focuses on what the tool returns rather than input details.

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

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

The description clearly identifies the resource being accessed: the user's current Pixly credit balance and plan. It lacks an explicit verb like 'gets' or 'retrieves', but the meaning is unambiguous and distinct from all sibling tools, none of which relate to credit or billing.

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

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

The description implies this is the tool to call when you need a user's credit balance and plan, but it does not explicitly state when to use it versus alternatives. Since no sibling tool serves a similar purpose, the lack of alternatives guidance is not misleading, but there is no direct usage instruction.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, establishing the safety profile. The description adds useful behavioral context beyond those: job duration expectations, polling cadence, and that result URLs are fetched upon completion. This is meaningful supplementary information without contradicting the annotations.

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

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

The description is two sentences with no filler. The primary action is front-loaded, and the second sentence delivers practical timing guidance. Every word earns its place.

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

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

For a single-parameter polling tool with an output schema, the description covers the essential workflow and timing expectations. It does not detail status values or failure behavior, but those are likely documented in the output schema, and the annotations already cover safety.

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

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

Schema coverage is 100% and the jobId parameter already includes a clear description ('Job id returned by a generation tool'). The description does not add any additional parameter-specific meaning, so it earns the baseline 3 for high schema coverage.

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

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

The description clearly states the tool's action ('check a generation job's status and fetch result URLs when it's done') and identifies its resource (generation jobs). It is unambiguous and distinguishes itself from sibling generation tools by focusing on status polling rather than creation.

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

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

The description provides explicit usage context by noting video jobs take 1-5 minutes and recommending polling with a few seconds between calls. It implies the tool is used after a generation job is submitted, though it does not name alternatives or state when *not* to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: newest-first ordering, the distinction between generations and uploads, and the fact that uploads are the only way to access local files. It doesn't mention pagination or exact return shape, but for a read-only list tool this is solid.

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 behavior, and the second sentence earns its place by explaining the uploads workflow. No fluff.

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

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

For a read-only list tool with no output schema, the description covers the main use cases and the uploads workflow. It doesn't describe the return format or pagination, but the annotations cover safety and the schema covers parameters. Slightly more detail on what fields are returned (e.g., r2Path) would make it fully complete, but it's already strong.

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

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

Schema coverage is 50%: the 'type' parameter has a description, but 'limit' does not. The description adds context for 'type' (uploads lists source photos, not generations) and explains the r2Path pickup, which goes beyond the schema. The 'limit' parameter is still undocumented in the description, but its meaning is fairly obvious from the schema (default 20, max 50).

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

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

The description clearly states the tool lists the user's recent generations, or uploaded source photos when type='uploads', newest first. It distinguishes itself from siblings by explaining the uploads case and why it matters (connectors cannot send bytes).

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 the 'uploads' type: when the user refers to a photo they added but have not run a tool on yet. It also explains the workflow context (user adds at pixly.app/app, tool picks up r2Path), which is strong guidance for an agent deciding between this and other tools.

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

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

The description adds behavioral context beyond the annotations: it states the tool costs credits from the user's Pixly balance and that the house, roof, driveway, sun direction, and neighbors remain unchanged. This complements the openWorldHint (adds elements) and destructiveHint false (non-destructive) annotations, providing clarity on scope and cost without contradicting them.

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

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

The description is two sentences, with the first sentence front-loading the core purpose and scope. It lists elements efficiently, then states constraints and cost. Every clause adds meaning with no fluff, making it appropriately concise and well-structured.

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

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

The description covers the tool's purpose, scope, constraints, cost, and the one-run composition behavior. The schema provides detailed parameter semantics, and the presence of an output schema means return format is documented elsewhere. It is complete enough for an agent to understand when and how to use the tool, though it could briefly mention the requirement of an exterior photo (though that is implied by the title and description).

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

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

Schema coverage is 100%, so all six parameters are thoroughly documented in the schema, including enums and descriptions. The description does not add parameter-specific semantics beyond what the schema provides; it gives a high-level overview that ties parameters together, but the schema already explains key behaviors like 'One run composes them all into one garden' in the include parameter. Thus the description adds little beyond the baseline.

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

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

The description clearly states the tool designs the garden of an exterior listing photo as one coherent scheme, listing specific elements (planting, terrace, pool, etc.) and explicitly noting what stays unchanged (house, roof, driveway, sun direction, neighbors). This distinguishes it from sibling tools that alter other aspects, and the phrase 'One run builds the whole scheme' clarifies its comprehensive 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?

The description clearly conveys it is for garden design, implying use when the user wants a full or partial garden makeover, and mentions the credit cost. However, it does not explicitly name alternatives or state when not to use it, relying on the agent to infer from the tool's name and purpose. It provides clear context but lacks explicit exclusions or comparisons to 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?

Beyond the annotations, the description discloses that the operation 'Costs credits from the user's Pixly balance,' a meaningful side effect an agent must know. It also reveals the camera behavior of landing exactly on the end photo. It does not mention asynchronous execution or failure modes, but with an output schema present and annotations already covering read-only and destructive hints, this is a strong addition.

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

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

The description is compact and well-structured: a first sentence stating the core transformation, a second illustrating the end-photo use case, and a third covering the main choices and cost. It is front-loaded with the purpose and contains no filler or redundant sentences.

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 10 parameters, full schema coverage, and an output schema, the description provides the essential high-level orientation: input photos, optional end photo, camera movement options, model/length/sound choices, and the credit cost. It does not spell out the two input-path alternatives (imageUrl vs r2Path), but those are thoroughly documented in the schema, so the description is largely complete for selection and initial 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 the baseline is 3. The main description adds conceptual context, such as the end-photo orbit example and the general choices of model, length, and sound, but it does not add parameter-level detail beyond what the schema already provides. The schema descriptions themselves are rich and handle the parameter semantics.

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

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

The description opens with 'Turn a start photo — and optionally an end photo — into a video,' which is a specific verb and resource that clearly identifies the tool's core purpose. It adds distinctive behavior by describing the camera traveling from the first photo and landing exactly on the second, and it mentions camera moves, prompts, model/length/sound. However, it never explicitly contrasts itself with sibling tools like cinematic_motion, so differentiation is implied rather than directly stated.

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

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

The description gives clear context for when to use the tool: converting a photo, and optionally a second photo, into a video, with an example of two kitchen views becoming an orbit. It also explains the choice between a camera move and a custom prompt. But it does not explicitly state when to prefer this tool over siblings like before_after_reel or cinematic_motion, nor does it list exclusions.

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

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

Annotations already provide readOnlyHint=false, openWorldHint=true, and destructiveHint=false. The description adds useful context beyond those fields by disclosing that the operation costs Pixly credits and that results are photorealistic with perspective/lighting matching. There is no contradiction with annotations.

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

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

The description is two sentences with no filler. The primary function and exact behavior are front-loaded, and the credit-cost note is appended concisely.

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

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

For a tool with full schema coverage, an output schema, and annotations covering safety, the description provides sufficient operational context: what it does, the visual expectation, and the cost implication. 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%, with each parameter already documented including enums and constraints. The description adds only light extra context via text examples, not parameter-level semantics, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: placing a photorealistic 3D monument sign with exact text onto a photo of an empty plot. It also names concrete use cases (price, area, SOLD) and quality attributes (perspective, lighting), which clearly separates it from siblings like virtual_staging 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?

The description clearly implies when to use this tool: when the user wants a sign on an empty plot photo. It does not explicitly name alternatives or exclusions, but the use context is clear enough that an agent can route to it appropriately.

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

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

Beyond the annotations, it discloses credit cost, default removal of joinery, the 'movable' mode exception, optional floor strip-back, and invariants like doors staying. There is no contradiction with destructiveHint=false because the tool edits a photo rather than deleting a stored asset.

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

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

Three dense sentences front-load the main purpose, then cover variant modes, constraints, and cost. There is no filler; every sentence contributes to correct selection and invocation.

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 detailed input schema, annotations, and output schema, the description supplies all remaining context: purpose, default behavior, variants, constraints, and cost. An agent has everything needed 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% and the schema already documents mode defaults, extras applicability, and the imageUrl/r2Path alternatives. The description adds emphasis but does not materially extend the parameter semantics.

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

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

The description names a precise operation (remove furniture from a photo), explains the resulting output (empty room with rebuilt surfaces, identical architecture/camera), and explicitly contrasts with declutter. This makes it clearly distinguishable from sibling editing tools like declutter_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?

It frames the tool as the blank-canvas restaging option and gives the key decision rule: Declutter is the opposite and keeps furniture. Mode behavior is also described in enough detail to know when fitted vs movable is appropriate.

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

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

The description adds valuable behavioral context beyond the annotations: it costs credits from the user's Pixly balance, preserves the original layout exactly, and omits written dimensions. This is more than the readOnlyHint/destructiveHint annotations alone provide, and there is no contradiction with them.

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

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

Three sentences, each carrying a distinct piece of information: core transformation, fidelity constraints, and cost. It is front-loaded and not padded, though the list of source image types is somewhat redundant with the schema.

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

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

Given the output schema and fully documented parameters, the description covers the key operational details: input types, output modes, fidelity behavior, and credit cost. It does not explain return values, but that is unnecessary because an output schema exists. The only minor gap is not restating the oneOf imageUrl/r2Path requirement, though 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 coverage is 100%, and the parameter descriptions already document look, r2Path, and imageUrl, including the 'either imageUrl or r2Path is required' constraint. The overall description repeats some input/output context but does not add new parameter-level semantics, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb and resource: turning a floor plan image into a polished 2D furnished plan or 3D isometric cutaway. It gives clear input examples and output forms, which distinguishes it from sibling tools like 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 is explicit about the input domain: any picture of a floor plan, including hand sketches, brochure photos, blueprints, and screenshots. It does not name alternative tools or state when not to use it, but the input criteria are clear enough to guide selection.

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

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

Beyond the annotations, the description reveals that the operation modifies only the lawn area while preserving other elements, and that it costs credits from the user's Pixly balance. This adds meaningful operational context not encoded in the annotations or schema. It does not contradict the annotations.

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

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

The description is two sentences with no filler: the first sentence defines the transformation and scope, the second states the cost. It is front-loaded and every phrase 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?

The description supplies the essential operational details: what gets transformed, what is preserved, and the credit cost. The input schema covers all parameters, and an output schema exists, so return-value explanation is unnecessary. An explicit 'when not to use' or sibling routing note would make it fully complete.

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

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

Schema description coverage is 100%: every parameter has a descriptive entry, including enums, defaults, and the either/or requirement between imageUrl and r2Path. The tool description itself adds no parameter-level detail, so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('Turn') and resource ('patchy, brown or bare grass in an exterior listing photo') and names the exact result ('healthy green lawn'). It also distinguishes the scope by explicitly preserving driveways, paths, beds, and the house, differentiating it from broader exterior edit tools.

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

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

The description gives clear trigger conditions ('patchy, brown or bare grass'), target context ('exterior listing photo'), and behavior scope ('leaving driveways, paths, beds and the house untouched'). It does not explicitly name sibling alternatives 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 valuable behavioral details beyond the annotations: a 1–2 minute runtime, the need to poll get_job until completion, and that it costs credits from the user's Pixly balance. It also reassures non-destructiveness by stating buildings, trees, and reflections remain unchanged, complementing destructiveHint=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?

Two sentences with no wasted words: the first states purpose and constraints, the second provides latency, polling, and cost. Every sentence contributes operational value and the key purpose is front-loaded.

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

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

For a moderately complex 6-parameter tool with an output schema, the description covers purpose, eligibility, runtime, polling, cost, and non-destructive behavior. Input selection is already handled by the schema's parameter descriptions, so nothing needed 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%, with each parameter already documented including enums, defaults, and constraints. The description adds no parameter-level detail beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the action ('Replace') and the specific resource ('sky in an exterior listing photo'), with explicit trigger conditions ('grey, overcast or blown-out') and the intended result ('natural clear blue sky'). It also distinguishes itself from sky-affecting siblings like day_to_night and reset_season by specifying the natural blue-sky outcome and preservation of building, trees, and reflections.

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

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

The description gives clear when-to-use guidance through the trigger conditions 'grey, overcast or blown-out sky', and practical usage expectations such as polling get_job and credit cost. It does not explicitly name alternatives or exclusions, but the conditions are sufficient for an agent to select this tool over 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 indicate readOnly=false and destructive=false; the description adds valuable context: 'Costs credits from the user's Pixly balance' and the invariance of geometry ('house, driveway, paths, camera angle stay exactly as shot'). No contradiction with annotations.

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

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

Two sentences with no filler, front-loaded with the core purpose and followed by concrete examples and a cost warning. Every sentence earns its place.

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

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

Given the schema covers all parameters, annotations cover safety profile, and the description adds credit cost and invariance constraints, the definition is complete for a mutation tool. An output schema exists, so return-format details are not required.

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 parameters are fully documented in the input schema. The description adds overall behavior but no additional per-parameter meaning beyond what the schema already states (e.g., season enum details). 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: 'Photograph the same property in another season' with concrete transformations (snow off ground/roof/branches, garden in leaf, summer to autumn/winter). Clear purpose, but it does not explicitly differentiate from sibling tools like replace_lawn or replace_sky, so it misses the top score.

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

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

Provides clear context for when to use: changing the season of a property photo, with examples. No explicit exclusions or named alternatives, but the intended use is evident from the description and season parameter.

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 and destructiveHint=false, so the description doesn't need to restate safety. It adds valuable behavioral context: the tool costs credits, preserves layout/fittings/windows/camera, and describes fallback behavior for invalid finishes ('falls back to auto') and for 'custom' with no note. This goes beyond the schema and annotations.

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

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

The description is well-structured and front-loaded with the core action, followed by constraints and cost. It is slightly long but every sentence carries information: scope, invariants, cost, and fallback behavior. The parameter descriptions in the schema are also well-written, so the overall definition is efficient.

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

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

The tool has 5 parameters, nested objects, and an output schema, and the description covers the key behavioral rules (fallbacks, custom notes, credit cost, invariants). It doesn't explain the output schema, but that's not required since an output schema exists. The only minor gap is not explicitly stating that imageUrl and r2Path are mutually exclusive, but the schema already says 'Either imageUrl or r2Path is required.'

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains the fallback behavior for mismatched finishes, the 'auto' agreement across surfaces, the relationship between 'custom' and notes, and the meaning of 'cabinets' (includes worktop and splashback). This is genuinely useful for an agent constructing valid calls.

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 ('restyle') with a clear resource ('one or more surfaces of a room') and enumerates concrete examples (repaint walls, change floor, reface cabinets, retile bathroom, refinish furniture). It also explicitly states what stays unchanged (layout, fittings, windows, camera angle), which distinguishes it from sibling tools like remove_furniture or virtual_staging.

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

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

The description clearly states when to use the tool (when the user wants to change surface finishes) and what it does not do (does not change layout, fittings, windows, camera angle). It does not explicitly name sibling alternatives or exclusion conditions, but the scope is clear enough to route an agent. The 'costs credits' note adds practical context.

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

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

The description adds valuable behavioral context not present in the annotations: it costs credits from the user's Pixly balance, it acts selectively ('each only where needed'), and it leaves the house unchanged. The annotations already mark it non-read-only and non-destructive, and the description does not contradict them.

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

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

The description is a single dense sentence that front-loads the purpose and packages scope, selectivity, and cost efficiently. It is not bloated, though the examples could be slightly trimmed without losing meaning.

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

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

For a 3-parameter tool with full schema descriptions and an output schema, the description supplies the missing business context: credit cost, selective application, and house preservation. It does not address alternative selection, but that gap belongs to usage guidelines; an agent still has enough to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description gives concrete color to the fix values (dull sky, dead grass, clean driveway, bins/hoses), but it largely restates what the schema already documents and adds no new mechanics for r2Path or imageUrl.

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: 'One-click retouch of an exterior listing photo,' then enumerates concrete fixes (sky, lawn, driveway, clutter) with the constraint 'with the house unchanged.' This clearly differentiates it from siblings like replace_sky, replace_lawn, and makeover_exterior, which imply broader or full transformations rather than selective touch-ups.

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 intended use is implied: an exterior photo needing selective retouching, not full replacement or restaging. However, the description never explicitly names alternatives or exclusion conditions (e.g., use replace_sky for full sky replacement, declutter_photo for interior clutter), so the agent must infer when this tool is preferred over a sibling.

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

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

Annotations already indicate readOnlyHint=false, so the write operation is expected. The description adds meaningful context beyond annotations: the purpose is to pre-import and cache a URL for reuse, which explains why a mutation occurs and why it is rarely needed. It does not detail side effects like duplicate imports, but given the simple scope, this is sufficient.

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

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

Two sentences with no wasted words. The 'Rarely needed' warning is front-loaded, and the rest explains the specific use case. Every sentence earns its place.

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

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

For a one-parameter tool with no output schema and annotations covering safety, the description is mostly complete. It explains why and when to use the tool and what it accomplishes. However, it does not mention the return value or how the imported photo can be referenced by other tools afterward, which is a minor gap given the reuse-oriented purpose.

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

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

The schema description already covers 100% of the parameter, specifying it must be a publicly reachable JPG/PNG/WebP URL up to 10 MB. The description adds no further parameter-level details, 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 clearly states the tool imports a photo into Pixly ahead of time, using a specific verb ('import') and resource ('photo into Pixly'). It distinguishes itself from generation tools that take an imageUrl directly, so an agent can tell it apart from sibling tools without comparing schemas.

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

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

Explicitly states 'Rarely needed' and gives the precise condition for use: importing a photo ahead of time to reuse a URL across tools without refetching. It also names the alternative class (generation tools) that should be preferred when the URL can be passed directly, leaving no ambiguity about when to use this tool.

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 readOnlyHint/destructiveHint annotations, the description adds meaningful behavior: the guarantee that 'nothing in the photo changes,' the 4096 px cap, the up-to-4x scale, and the credit cost from the user's Pixly balance. It does not mention async behavior or failure modes, but the output schema covers return expectations.

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

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

Three dense, well-ordered sentences: what the tool does and its limits, the no-change guarantee, and the cost structure. Every sentence carries useful information 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?

With full parameter schema coverage and an output schema present, the description provides the remaining decision-critical context: max output size, source selection, fidelity guarantee, and credit pricing. An agent has enough information to call the tool correctly.

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

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

Schema description coverage is 100%, giving a baseline of 3, but the description adds pricing semantics by tying r2Path from list_library to the free case and 'your own photo' to the 1-credit case, which is not present in the schema field descriptions.

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

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

The description opens with a specific verb and resource: 'Enlarge a photo by up to four times with real detail, to a maximum of 4096 px on the long edge.' This clearly differentiates it from siblings like enhance_photo and edit_staged_photo, and the use cases (print, MLS uploads, large screens) reinforce intent.

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

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

It gives clear context for when to use the tool and how to source the input: pass a Pixly-made result's r2Path from list_library for the free case, or use your own photo for 1 credit. It does not explicitly name alternative tools or when-not-to-use cases, so it falls just short of the top score.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description doesn't need to restate those. The description adds valuable behavioral context: HD and watermark-free results, the possibility of a free second version under `versions`, and that the second version may take longer. It also discloses that numImages and stagingQuality are ignored, which is important behavioral transparency beyond the schema's deprecated flags. Minor gap: doesn't mention what happens if both imageUrl and r2Path are provided, but that's a parameter-level detail.

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

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

The description is a single paragraph that front-loads the core purpose and then adds practical details. It's slightly dense but every sentence earns its place: purpose, alternative use cases, output quality, version behavior, and cost. The mention of 'get_job then lists both under `versions`' is a bit nested but still clear. Could be split into two sentences for readability, but it's not bloated.

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

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

Given the tool's complexity (7 params, output schema present, sibling tools like restyle_room and remove_furniture), the description covers the essential decision points: what it does, when to use it, what to expect in output, and how to handle the second version. The output schema exists, so return values don't need to be described. The credit cost and watermark-free promise are extra context that helps an agent set user expectations. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds value by explaining the style parameter's default recommendation ('modern-minimal' or 'scandinavian' suit most listings') and by clarifying that numImages and stagingQuality are ignored. It also explains the relationship between r2Path and imageUrl as alternatives. This goes beyond the schema's descriptions, which are already detailed.

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

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

The description clearly states the tool's function: AI virtual staging that furnishes and styles a room photo in a chosen interior design style. It also explicitly names alternative use cases ('redesign this room' or 'show this room in another style'), which distinguishes it from siblings like restyle_room or remove_furniture. The verb 'furnish and style' is specific and the resource (room photo) is clear.

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

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

The description explicitly says this is also the tool for 'redesign this room' or 'show this room in another style', which helps an agent choose it over siblings like restyle_room. It also provides guidance on handling the optional second version: 'show the user both and let them pick'. It mentions credit costs, which is a practical usage consideration. No explicit exclusions, but the context is clear enough.

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