Photo AI Studio

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

Annotations already indicate this is read-only, idempotent, and non-destructive. The description adds valuable non-obvious behavior: a connected Photo AI Studio account is required and calling the tool starts the sign-in flow. This goes beyond what annotations provide and helps the agent anticipate side effects.

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 short, front-loaded with the tool's main purpose, and immediately followed by the critical output detail and account/sign-in note. Every sentence serves a distinct purpose without redundancy.

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

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

Given the low parameter count, rich annotations, and simple output (theme slugs), the description covers the essentials: what the tool returns, why it matters, and the auth prerequisite. It stops short of describing the exact response shape or whether tag and gender can be combined, but these are minor given the tool's simplicity.

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 fully documents tag and gender. The description adds only that filtering is optional and by gender or keyword, which lightly reinforces the semantics but does not materially extend 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 a specific action ('Browse'), a resource ('photo themes'), optional filters, and the key output ('theme slugs that generate_photo expects'). However, it does not distinguish browse_themes from its sibling list_photo_themes, which appears to serve a very similar 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 the tool should be used before generate_photo because it returns the expected slugs, and it mentions the account/sign-in prerequisite. It does not explicitly compare against list_photo_themes or state when not to use this tool, leaving some selection judgment to 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?

The description discloses important behavioral traits beyond the sparse annotations: credit costs, the need for a connected Photo AI Studio account, and the side effect of starting a sign-in flow. It does not explicitly mention the asynchronous prediction_id/polling behavior in the main text, but the wait_for_result parameter schema covers that. 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 compact and front-loaded: core purpose and cost appear first, followed by a clean bullet list of types. Every sentence contributes value, with no repetition of schema details. The structure is easy to scan and parse.

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 16-parameter tool with no output schema, the description provides a solid mental model: what the tool creates, which parameters belong to which type, and the auth/cost context. The return-and-polling behavior is only present in the wait_for_result parameter description rather than the main description, but that is acceptable because the full tool definition includes it. The description is complete enough for an agent to select the tool and construct a valid request.

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?

With 100% schema description coverage, the baseline is 3, but the description adds a higher-level type-to-parameter mapping (image_to_video uses image_url/prompt; ugc uses script/voice_id; product_holder uses product_image_url). This helps an agent select the correct parameter set per type beyond what each property's schema description states. The cost implications tied to output_type are also useful.

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, 'Create an AI video,' and immediately enumerates three concrete generation types (image_to_video, ugc, product_holder). This clearly differentiates the tool from sibling tools like generate_photo and edit_image, which focus on static image tasks. The cost line also clarifies that product_holder can produce an image, adding useful scope nuance.

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

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

The description gives clear context for when to use this tool—creating AI videos or product_holder images—and maps each type to its key parameters. However, it never explicitly states when not to use it or points to alternatives, such as using generate_photo for normal photos. The account-requirement note is a helpful prerequisite but not a routing rule.

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), it discloses credit costs per operation, the sign-in side effect, and the CDN-URL requirement. It could also describe the asynchronous output/polling behavior, which is absent from the main description, so it is not a perfect 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?

The description is long but scannable: cost summary first, then a bulleted operation list, then constraints. Each section earns its place, though a compact return-value or polling note could make it tighter.

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 19 operations, 16 parameters, and no output schema, the description covers operations, costs, auth, and URL constraints well. However, it never explains what the tool returns (e.g., a prediction_id or polling with get_prediction), leaving a meaningful gap for an agent.

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 a valuable operation-to-argument matrix and the global CDN constraint. It omits optional parameters like hair_color and num_images from the list, but it clearly covers the required argument relationships.

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 'Edit a photo with one of 19 AI operations' and then enumerates every operation, making the resource and action unambiguous. This clearly differentiates it from siblings like generate_photo, upload_image, and create_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?

It establishes a clear use context: edit existing photos with one of these specific operations, and sets prerequisites such as 'Every image argument must be a CDN URL from upload_image' and 'Requires a connected Photo AI Studio account.' It does not explicitly name sibling alternatives or when-not-to-use cases, so it stops short of 5.

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

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

Beyond the annotations (readOnly=false, destructive=false), the description adds that generation costs 100 credits per photo, requires a connected Photo AI Studio account, and starts the sign-in flow. These are meaningful behavioral and side-effect disclosures. It does not cover rate limits or async result handling, though wait_for_result is described in the schema.

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

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

Three tight sentences front-load the purpose, then provide workflow prerequisites, then the account requirement. No redundant or filler content; every sentence adds needed context.

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 a 9-parameter tool with no output schema, the description communicates the two modes, prerequisites, cost, and auth flow. Conditional requirements and the prediction_id/async pattern are left to parameter descriptions, which document them, so the overall tool definition is reasonably complete but not exhaustively summarized up front.

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 parameter baseline is 3. The description adds workflow relationships (images come from upload_image; theme slugs come from browse_themes) but does not add detailed semantics for individual parameters beyond what the schema already states.

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: 'Generate AI photos from face images,' and distinguishes the two generation modes ('preset theme or custom prompt'). It also references sibling tools by workflow ('upload_image first,' 'browse_themes'), which separates this generation step from upload, theme browsing, editing, and video 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?

It gives explicit usage prerequisites: upload face photos with upload_image first and find theme slugs with browse_themes. It also discloses the account/sign-in requirement. It does not explicitly state when-not-to-use vs edit_image or create_video, so it misses full exclusion 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 (readOnly, idempotent, non-destructive), the description discloses an important behavioral trait: calling the tool can start the sign-in flow. It also explains the connection requirement, providing useful context that annotations do not capture.

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 earning its place: what the tool returns, when to use it, and the auth prerequisite/side effect. It is front-loaded with the core purpose and contains no filler.

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

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

For a zero-parameter, read-only account lookup with no output schema, the description is complete: it states the resource, the returned fields, when to call it, and the sign-in side effect. 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?

The tool has zero parameters, so there is no parameter semantic burden on the description. The input schema already covers the argument space completely and the description sensibly omits parameter details. This matches the 0-params baseline of 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 uses a specific verb and resource: 'Get the connected Photo AI Studio account' and enumerates the exact returned information (credit balance, total predictions, membership date). This clearly differentiates it from sibling tools like generate_photo or get_prediction.

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 tells the agent when to call this tool: 'Check this before generating, because every photo costs credits.' It also gives prerequisites and a side effect ('Requires a connected Photo AI Studio account. Calling this tool starts the sign-in flow.'), though it does not discuss when not to use it or name alternatives.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, and the description adds meaningful context about what the explanation covers—authentication state, REST endpoints, and credit purchasing. It accurately signals a safe, side-effect-free informational call with no hidden mutations.

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 dense sentence front-loads the core purpose ('how an agent actually calls Photo AI Studio') and then lists the distinct covered areas. Every phrase carries information; there is 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?

For a parameterless documentation tool, the description covers the key areas a calling agent would need—MCP connection, unauthenticated discovery, REST fulfillment, and credits. It does not specify the exact output format of the explanation, but with no output schema that is a minor gap, and the purpose itself makes the return type ('an explanation') evident.

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 the baseline is 4; the description doesn't need to elaborate on any input schema. It adds no misleading parameter info, and the absence of parameters is consistent with an informational tool.

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 ('Explain') and names the exact resource: how an agent calls Photo AI Studio over MCP, including discovery endpoints, REST fulfillment API, and credit purchasing. This clearly differentiates it from siblings such as get_service_overview or get_pricing by focusing on integration mechanics rather than pricing or service status.

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 makes the tool's context obvious: an agent needing to understand MCP connection, unauthenticated discovery endpoints, REST fulfillment, or credit purchases. It doesn't name sibling alternatives or state explicit 'when not to use' exclusions, 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?

The description adds valuable behavioral context beyond the annotations: it requires a connected Photo AI Studio account and warns that calling the tool can start the sign-in flow. This is non-obvious side-effect information that the readOnly/idempotent hints do not convey. There is no direct contradiction with the annotations.

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

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

The description is compact and front-loaded: the first sentence states the core purpose and return value, and the second sentence adds only the essential auth caveat. There is no redundant or filler content.

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

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

For a one-parameter read-only polling tool, the description covers what the operation is, how to identify it, what the tool returns, the account prerequisite, and the sign-in side effect. The lack of an output schema is adequately compensated by the explicit statement that it returns the state and result URL.

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

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

The single parameter prediction_id is already fully documented in the input schema with the same provenance information ('returned when the operation started'). Since schema description coverage is 100%, the description does not add meaningful parameter-level detail 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 a specific action — checking an operation started by generate_photo, edit_image, or create_video — and the expected result (state and result URL). It is distinct from the sibling list_predictions by focusing on a single operation, though it does not explicitly name that sibling or draw the contrast.

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 identifies when to use the tool: after an asynchronous operation has been started and you need its state or finished result URL. It also notes the account requirement and sign-in flow, but it does not mention alternative tools such as list_predictions or state when not 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds what data is returned (credit-package/subscription pricing and per-photo credit cost) but does not disclose other behavioral traits such as response format or data freshness. This meets the lowered bar but adds only modest extra context.

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 sentence that is front-loaded with the action and resource, and packs in the key differentiators (credit packages, subscriptions, per-photo credit 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?

For a zero-parameter, read-only, idempotent lookup with no output schema, the description is fully sufficient. An agent knows exactly what the tool does and can invoke it without needing additional context about parameters, side effects, or return shape.

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

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

There are zero parameters, so the schema already trivially covers 100% of parameters. The description adds no parameter-specific detail, but none is needed. The zero-parameter baseline of 4 applies, and the description clearly states what the tool returns, making the lack of param docs irrelevant.

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 has a specific verb ('Get') and resource ('Photo AI Studio credit-package and subscription pricing'), and explicitly enumerates what is included ('credit cost per generated photo'). This clearly distinguishes it from siblings like get_service_overview and get_api_capabilities, which could otherwise overlap.

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 use case: when an agent needs pricing information. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or conditions. For a simple zero-parameter lookup tool, the implied context is adequate but not 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 carry the safety profile (read-only, idempotent, non-destructive), so the description only needs to add context beyond that. It adds useful behavioral detail by stating the overview includes best-fit use cases, guidance, and llms.txt content links, which is enough for an agent to know what kind of result to expect.

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 sentence, front-loaded with the action ('Get an overview'), followed by a clear ccolon-separated list of what the overview contains. No waste, no repetition of annotations.

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

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

For a zero-parameter read-only overview tool with no output schema, the description is largely sufficient: it tells the agent what content will be returned and why the tool exists. A slight gap is the lack of a concrete response format description, but the enumerated content list mitigates that.

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 the rbric baseline of 4 applies. There is nothing schema-side to explain, and the description appropriately does not invent parameter 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?

States a specific verb and resource: 'get an overview of Photo AI Studio'. It enumerates the content categories (what it does, when to use, best-fit use cases, key links), which clearly establishes its role and distinguishes it from more scoped sibling tools like get_pricing or get_api_capabilities.

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 mentions that the overview contains 'when to use it' and 'best-fit use cases', but it does not itself tell the agent when to choose this tool over siblings or suggest it as a starting point. There are no explicit exclusions or alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe read-only operation. The description adds minor context by noting the return of category page URLs, but it does not disclose anything deeper such as pagination, ordering, or coverage limits. 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 a single information-dense sentence with the verb and resource front-loaded, followed by concrete examples and the return format. Every element earns its place 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?

For a zero-parameter, read-only listing tool with annotations covering the safety profile, the description adequately conveys what is returned (theme categories and page URLs). It could be slightly more complete by clarifying the boundary with browse_themes, but the low complexity lowers the bar.

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

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

The tool has zero parameters and schema coverage is 100%, so the description has no parameter burden to carry. Per the rubric, a 0-parameter tool earns a baseline of 4, and the description appropriately focuses on the result rather than inputs.

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

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

The description states a specific verb and resource: 'List Photo AI Studio photo theme categories' with concrete examples (professional headshots, dating, wedding, graduation) and the return value (URL of each category page). It is clear about what the tool does, though it does not explicitly differentiate itself from the sibling browse_themes.

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 usage context is implied: an agent would call this to get a catalog of photo theme categories with their URLs. However, there is no explicit guidance on when to choose this over browse_themes or any other alternative, and no exclusions or prerequisites are 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?

Beyond the readOnlyHint, idempotentHint, and destructiveHint annotations, the description reveals that a connected Photo AI Studio account is required and that calling the tool starts the sign-in flow. This is a meaningful behavioral side effect not encoded in the annotations and critical for an agent to know before invoking.

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 core listing behavior front-loaded and the auth/sign-in context clearly separated. Every sentence carries necessary information without redundancy or 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 simple list tool with optional paging and state filtering, the description covers scope, parameters, and an important auth side effect. No output schema is needed for an obvious list result, and the agent has sufficient context 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 page, limit, and state are already documented in the input schema. The description's mention of 'paging' and 'state filter' adds minimal value beyond what the schema 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 opens with a specific verb and resource: 'List past generations, edits, and videos,' clearly indicating a read-only collection operation. It distinguishes itself from sibling creation tools and from the singular get_prediction by emphasizing 'past' and batch listing.

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 tool is for browsing past operations through 'List past' and the optional state filter, but it does not explicitly state when to prefer this over get_prediction or when not to use it. No alternative tools or exclusions are named, leaving usage guidance mostly 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?

The description discloses important behavioral traits beyond annotations: the 10 MB limit and the side effect that calling the tool starts the sign-in flow and requires a connected Photo AI Studio account. This adds useful context that annotations alone do not provide.

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

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

The description is compact and front-loaded: it states the purpose, workflow role, accepted inputs, size limit, and prerequisite/side effect in two short paragraphs. Every sentence contributes meaningful guidance, 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?

For a simple two-parameter upload tool with no output schema, the description is complete: it states the return value (a URL), the input formats, the size limit, the account requirement, and the sign-in side effect. It also explains how this tool fits into the broader sibling-tool workflow.

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

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

The input schema already describes both parameters clearly and fully, so the baseline is 3. The description adds the 10 MB limit and summarizes the base64 use case, providing extra value beyond the schema without repeating it verbatim.

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: 'Upload an image to the Photo AI Studio CDN and get back a URL.' It also differentiates from sibling tools by noting that generate_photo, edit_image, and create_video consume CDN URLs, so upload_image is the entry point.

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: it explicitly says to start here before generate_photo, edit_image, or create_video, and explains the choice between public URL and base64 data. It does not explicitly state when not to use it, such as when a CDN URL is already available, but the workflow context is strong.

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