switch

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful behavioral context: it frames the tool as 'Switch Vision — watch and understand like a human', describes what it extracts (tone, mood, structure), and clarifies that 'Switch resolves its own links' internally. It doesn't discuss rate limits or latency, but with annotations covering safety, this is strong.

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

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

The description is three sentences, front-loaded with the core purpose, followed by input specifics and usage context. Every sentence earns its place: no filler, examples are embedded naturally, and the structure flows from what to how to when.

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

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

For a 2-parameter tool with no output schema, the description covers all necessary context: accepted input types, optional question, use case, and a hint at the output ('answer a question about it'). It even mentions the tool works on images as well as videos, which is a useful scope clarification not obvious from the 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 coverage is 100%, but the description adds significant meaning beyond the schema. It expands video_url to include 'public https video URL, including YouTube' and specifies Switch video/asset IDs from list_my_videos / list_my_assets / upload_media. It also gives concrete question examples, enriching the semantics of both parameters beyond the schema's basic 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 states a specific verb+resource: 'watch and understand a video (or image) like a human and answer a question about it'. It enumerates the analysis dimensions (scenes, subjects, actions, on-screen text, pacing, mood, sentiment), which clearly distinguishes it from siblings like video_to_prompt or analyze_video_report. This is a clear, specific 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 explicitly tells when to use the tool: 'Use this whenever the user gives you a reference video and wants its style, energy, structure or content understood — for example before making a new video that matches it.' It also explains the two input modes (public URL vs Switch video/asset ID), providing clear context for selection against 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?

Beyond the readOnlyHint=false annotation, the description discloses significant behavioral traits: it bills per second with a 30-second minimum, re-running the same video/question is not charged again (with force to override), it returns a report_id immediately rather than a synchronous result, and tokens are returned automatically if it cannot finish. This is exactly the context an agent needs to manage 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?

The description is dense but every sentence earns its place. It front-loads the core purpose, then logically flows through inputs, billing, re-run behavior, return type, polling, failure handling, and alternatives. No filler words; the length is justified by the tool's complexity.

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 no output schema, the description adequately covers return semantics (report_id + polling via get_vision_report) and lists the report's content categories. It also explains billing constraints, the cached-result behavior, and the distinction from the lighter analyze_video tool. This is a well-rounded description for a complex tool.

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

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

Although the schema already documents all four parameters, the description enriches meaning by explaining duration_seconds is required for external files but auto-measured for YouTube/Switch videos, and that the 'force' parameter overrides the default cached-report behavior. This clarifies real-world usage beyond the schema's field-level definitions.

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 runs the full Switch Vision analysis on a video, producing a premium report with specific categories (overview, timeline, audio, visual craft, story/retention, transcript, prompts, metadata). It explicitly contrasts with the sibling analyze_video tool, making its unique purpose unmistakable.

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 explicit when-to-use guidance: use for full paid report vs. analyze_video for quick questions. Details input options (public URL or Switch video id), duration_seconds requirement for external files, billing rules (3 tokens/sec, 30s minimum), and the polling flow via get_vision_report. This is comprehensive and directly actionable.

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 establish read-only and idempotent behavior. The description adds that the tool returns a styled prompt stack rather than a direct image, and that it should be followed by generate_image, providing useful behavioral context beyond safety 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?

The description is two sentences, front-loaded with the core purpose, followed by options and output guidance. Every word contributes, with no redundancy or 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 simple read-only tool with no output schema, the description covers purpose, output (prompt stack), usage context (pair with generate_image), and parameter choices. Annotations cover side-effect safety, making this sufficiently 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 coverage is 100%, so the baseline is 3. The description mentions 'Choose grade: warm golden, cool noir, or moody desaturated' but does not add information beyond the schema's detailed enum descriptions. The 'for your shot' phrase weakly hints at the subject parameter, but adds little value.

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 applies an ARRI Alexa anamorphic widescreen film look, giving a specific verb and resource. It differentiates from sibling apply_* tools by naming the exact cinematic style and available grades.

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 'pair it with generate_image', indicating when to use the tool as a preparatory step for image generation. It does not mention alternatives or exclusions, but the style-specific context is 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?

The annotation readOnlyHint=true already indicates a read-only operation. The description adds value by specifying the output format ('styled prompt stack') and intended usage ('pair it with generate_image'), which clarifies behavior beyond the annotation. There is no contradiction with the idempotent hint; the tool simply returns a string.

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 concise and front-loaded, with three short phrases conveying the style, variants, and output. Every sentence earns its place, and there is no wasted wording. It is well-structured for quick scanning.

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 simplicity of the tool (2 params, no output schema), the description is largely complete: it states the purpose, output, and usage guidance. The schema covers parameters, and annotations cover safety. It could benefit from explicit guidance on when not to use it or how it compares to similar apply_* tools, but it is sufficient for this level of complexity.

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

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

Schema description coverage is 100%, so the schema already documents both parameters and their enums with examples. The tool description adds minimal extra meaning—just restating 'classic studio or golden-hour outdoor', which aligns with the schema's enum descriptions. Since the schema does the heavy lifting, a 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 clearly states it returns a styled prompt stack for a graphic editorial portrait, with specific style variants (classic studio or golden-hour outdoor). It uses a specific verb ('returns') and resource ('styled prompt stack'). However, it does not explicitly differentiate from sibling tools like apply_high_fashion_editorial, which could overlap in 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 usage ('pair it with generate_image') and mentions the two style options, giving some context for when to use it. However, it does not explicitly state when to use this tool over alternatives, nor does it provide exclusions or prerequisites. The guidance is inferred from the style description rather than explicitly stated.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description's addition of 'returns the styled prompt stack' gives concrete behavioral context beyond those flags. It does not overstate side effects and aligns with the read-only nature, though it could add a bit more about output format specifics.

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, front-loads the core purpose, uses a compact list for photographer moods, and ends with the essential return/usage note. Every word adds value with no redundancy.

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

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

For a style-applier tool with a well-documented schema and no output schema, the description adequately explains what the tool returns (styled prompt stack) and how to use it (pair with generate_image). It covers the necessary workflow without requiring extra detail about output structure.

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%, providing the baseline, but the description enriches style semantics by mapping friendly names like 'Mario Testino glossy' and 'Steven Klein dark cinematic' to the enum values. It also clarifies that subject is what you want to shoot, adding practical use context 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 applies high-fashion editorial style, specifically listing photographer moods and noting it returns a styled prompt stack to pair with generate_image. This distinguishes it from sibling style tools like apply_cinematic_anamorphic or apply_travel by focusing on high-fashion editorial energy.

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 strong contextual guidance: use this for high-fashion magazine/editorial shots and pair the output with generate_image. It does not explicitly say when not to use it versus sibling tools, but the clear stylistic focus and paired workflow give adequate direction.

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 provide readOnlyHint and idempotentHint. The description adds key behavioral context by disclosing that the tool returns a prompt stack rather than an image, and details the three style variants. 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?

The description is three sentences, front-loaded with the core purpose. Each sentence earns its place: aesthetic definition, flavor list, and output/workflow. No fluff 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?

For a simple 2-parameter tool with no output schema, the description covers purpose, flavor options, and the essential workflow (pair with generate_image). It could be more explicit about the output stack structure, but the combination of schema and description is adequate.

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% with detailed enum descriptions (e.g., 'digital_phone = Sony A7IV + 50mm f/1.4 GM phone-style realism') and subject examples. The description merely restates the three flavor names without adding new parameter meaning, so it stays at 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 creates a 'phone-shot amateur look' with specific aesthetic qualities ('casual, candid, pore-level real'), and lists three distinct flavors. It also states it 'returns the styled prompt stack' for pairing with generate_image, distinguishing it from sibling apply_* 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?

Provides clear context for when to use (when a realistic, candid phone aesthetic is desired) and instructs to 'pair it with generate_image.' It does not explicitly list alternatives or exclusions, but the specialized purpose makes the usage obvious.

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 idempotentHint=true, so safety is covered. The description adds useful behavioral context by stating it 'returns the styled prompt stack' and instructs pairing with generate_image, exceeding the baseline set by annotations alone.

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 concise, front-loaded with the core purpose, and each sentence earns its place. It avoids redundancy and stays within three short 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?

For a simple tool with two parameters and no output schema, the description adequately explains the purpose, camera choices, return type, and downstream usage with generate_image. It complements the schema and annotations effectively.

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 parameters are well documented. The description adds extra meaning by mapping the style enum to specific camera bodies (Canon R5 + 85mm f/1.2 vs Hasselblad H6D + 80mm), reinforcing the parameter semantics 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 function: it applies a golden-hour rim-light editorial portrait style and returns a styled prompt stack. It distinguishes itself from sibling apply_* tools by specifying the unique 'magic hour portrait' aesthetic and camera options.

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 on usage: choose a camera and then pair the returned prompt stack with generate_image. It implies the workflow without explicitly excluding alternatives, fitting the 'clear context, no exclusions' level.

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 that the tool returns a styled prompt stack, which goes beyond the readOnlyHint and idempotentHint annotations. This clarifies it is a safe, side-effect-free operation that only generates content for later use, improving agent understanding of the tool's behavior.

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

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

The description is three sentences, each with a distinct purpose: stating the function, listing options, and explaining the return value and next step. It is concise, well-structured, and free of redundant information.

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

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

For a simple tool with two parameters and no output schema, the description covers purpose, options, return value, and next-step guidance. The only minor gap is the exact structure of the 'styled prompt stack,' but this is likely evident from the generate_image context. Overall, it is complete enough for its complexity.

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

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

The input schema already provides comprehensive descriptions for both parameters, including detailed enum explanations. The description adds no additional parameter semantics; it merely lists the same genres. Given 100% schema coverage, 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 tool's function: applying a cinematic film look with specific genre choices, listing five distinct styles. It distinguishes from sibling apply_* tools like apply_travel or apply_product by focusing on movie scene genres. The verb 'apply' and resource 'movie scene' are explicit.

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 instructs to pair the output with generate_image, indicating the intended workflow. It provides a choice of styles, giving context on when to use it. However, it does not explicitly exclude other apply_* tools or mention alternatives, so it is clear but not exhaustive.

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 and idempotentHint. The description additionally clarifies that the output is a prompt stack rather than an actual image, which is key behavioral context. 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, front-loaded with 'Product photography,' then enum-style choices and the return value/usage. Every word is purposeful; 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?

Given the simple 2-parameter schema and no output schema, the description fully covers what the tool does, what it returns, and how to chain it with generate_image. Complete for agent selection and 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 coverage is 100%, with descriptive enum values already explaining each style option. The description adds little beyond restating the four choices and does not add extra meaning to the subject parameter.

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 explicitly states this is for product photography and lists four concrete style options, clearly distinguishing it from other apply_* sibling tools. The action of returning a styled prompt stack is specific and immediately understandable.

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 clearly positions the tool for product photography and instructs the agent to pair it with generate_image for the final image. It does not explicitly mention when not to use it or directly compare to sibling apply_* tools, but the domain label provides enough 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?

Beyond the readOnly and idempotent annotations, the description adds valuable behavioral details: real architecture is preserved exactly (no invented buildings), and attaching a reference image triggers an architecture lock. It also clarifies that the tool returns a prompt stack, not an image, which sets expectations for downstream use.

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?

Five sentences, each earning its place: category, constraint, subject options, reference-image behavior, and output/next-step. The description is front-loaded with the most important information and has 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 two-parameter style tool with strong annotations and no output schema, this description is fully sufficient. It explains the return type, the core architecture-preservation behavior, the subject list, and how to use the result with generate_image. No critical information 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 both parameters are already well-documented. The description echoes the enum values but doesn't add significant new meaning. The mention of a reference image is useful but not tied to any schema parameter, creating slight ambiguity.

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 luxury travel/hotel editorial style and returning a styled prompt stack. It differentiates from sibling apply_* tools by focusing on the travel domain and the architecture-preservation rule. The title and description together make 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 gives strong usage context by specifying the domain (luxury travel/hotel editorial), listing subject options, and explaining the pairing with generate_image. It doesn't explicitly name alternative tools or state when not to use it, but the context is clear enough for an agent to decide.

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 mark the tool as read-only and idempotent. The description adds behavioral context by clarifying that it 'returns the styled prompt stack' rather than an image, and by suggesting it should be paired with generate_image. This goes beyond the annotation hints and helps set expectations for the output.

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 concise sentences with the purpose upfront, followed by concrete options and output behavior. Every sentence earns its place and there is no redundant repetition of schema details. It is well-structured and easy to scan.

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 2-parameter, read-only style tool with no output schema, the description is complete. It explains what the tool does, what the output is (a prompt stack), how to use it (pair with generate_image), and enumerates available choices. No critical information 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 input schema fully documents both parameters with per-enum descriptions, so baseline is 3. The description adds value by listing the style choices in natural language and framing them with the 'casual captured' vibe, which reinforces the enum semantics and helps the agent understand the aesthetic intent.

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 this tool applies a user-generated content aesthetic, lists the specific style options (phone shot, film point-and-shoot, mirror selfie, car selfie), and explains it returns a prompt stack for generate_image. This distinguishes it from other apply_* siblings by emphasizing casual, real-person realism rather than cinematic or editorial styles.

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 provides clear context: use this when you want content that 'looks like a real person captured it casually,' and it guides the workflow by saying 'pair it with generate_image.' It does not explicitly list when not to use it or mention alternative tools, but the style choices and intended pairing make the use case evident.

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 readOnly and idempotent annotations already present, the description adds that the tool returns a prompt stack rather than an image, and that it should be paired with generate_image. This contextualizes the output without contradicting 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 concise sentences, front-loaded with the domain and styles, no filler. 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 simple style tool with 2 parameters and full schema coverage, the description sufficiently explains the output (prompt stack) and next step (use generate_image). No output schema is required and 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?

The schema provides 100% coverage, including detailed enum descriptions for style and an example for subject. The description does not need to add parameter details, so baseline 3 is appropriate.

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

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

The description clearly identifies the tool as applying wellness/yoga/fitness/lifestyle campaign styles (warm amber, cinematic, or cyan beach) and states it returns a styled prompt stack to pair with generate_image. This distinguishes it from sibling style tools by domain and output type.

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 usage for wellness-themed shots and instructs pairing with generate_image, but does not explicitly state when to choose this over sibling apply_* tools (e.g., apply_travel) or any exclusions. It provides a clear context but no direct 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?

The description adds important behavioral details beyond annotations: 'Already-saved images stay in your library; nothing is deleted or refunded' and 'Returns how many images were saved out of how many you requested.' This goes beyond the simple mutation/idempotent hints and clarifies side effects and return value.

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

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

The description is two sentences: the first states purpose and scope, the second covers side effects and return format. Every sentence adds value with no redundancy, and it is front-loaded with the action.

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 mutation tool with no output schema, the description fully explains behavior, side effects, and return value. Combined with the idempotentHint annotation and schema parameter description, it leaves no important gaps for the 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?

The schema already provides 100% coverage for the single taskId parameter with its own description ('Task id from generate_image or list_my_tasks'). The tool description does not add additional semantic meaning beyond restating 'by task id', so it meets the baseline for comprehensive 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 states 'Stop one of your generation tasks by task id' with a specific verb and resource, and clarifies it works on queued AND running tasks. This clearly distinguishes it from sibling tools like generate_image or get_video_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?

It explicitly specifies when the tool applies ('queued AND running tasks'), providing clear context for its use. It does not mention alternatives or exclusions, but the scenario is well-defined enough for an agent to decide when to invoke 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 and idempotentHint, covering the safety profile. The description adds the optional estimatedCost behavior but does not disclose additional side effects, permissions, or edge cases, which is acceptable given the simple read-only nature.

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, logically structured, with the main purpose first and optional behavior second. Every word earns its place with no redundancy.

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

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

For a read-only tool with one optional parameter and no output schema, the description is complete. It clearly states what it checks, what it returns, and how the optional parameter alters the result, making it self-sufficient for an agent to select and invoke 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?

The schema covers the single optional parameter with 100% coverage, and the tool description reinforces the same meaning ('USD', 'afford it'). The description adds marginal value beyond the schema but does not provide new semantic information.

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 checks daily Switch spending and returns spent, limit, and remaining. It uses a specific verb 'check' with a clear resource, and the optional affordability check distinguishes it from any sibling tool.

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: use for checking daily spending and optionally testing affordability. It does not explicitly mention alternatives or when not to use, but no competing balance tool exists among siblings, so implicit usage is sufficient.

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 and idempotentHint, so no contradiction. The description adds useful context beyond annotations by detailing the response shape and the polling-friendly behavior, which is relevant for an agent deciding whether to call this repeatedly.

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, front-loaded with the core purpose ('Polling-friendly status check'), and every clause adds value. No fluff or repetition of schema details.

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

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

For a simple single-parameter tool with no output schema, the description covers the return fields and the polling use case, making it sufficiently complete for the agent to understand the tool's basic behavior. It does not cover error cases or edge conditions, but these are less critical for such a simple read-only operation.

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% for the single parameter, taskId, which is described as 'Task id to check.' The description does not add new parameter details beyond the schema, but it does mention 'one of your tasks' which is a minor contextual reinforcement. Baseline 3 is appropriate given the schema adequately documents the parameter.

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 verb 'check' and the resource 'job status', and specifies it returns a slim shape with status, progressPct, and eta. It distinguishes itself from siblings by emphasizing the polling-friendly lightweight nature, which differentiates it from heavier status tools like get_video_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 conveys that this tool is for polling scenarios ('Polling-friendly') and explains the benefit ('without refetching the full payload'), providing clear context for when to use it. However, it does not explicitly name alternatives or state when not to use it, so it stops short of full exclusionary 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?

With readOnlyHint=false, the description correctly indicates a mutating operation (video to depth map). It adds valuable behavioral context: billing per second, immediate task_id return, asynchronous processing with polling, and automatic token refund on failure. This goes beyond the annotation and is transparent about cost and failure behavior.

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

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

The description is compact yet dense, covering purpose, input options, billing, async workflow, and failure handling without fluff. Each clause contributes meaningful information. It could be slightly shorter, but the structure is logical and 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 an async creation tool with no output schema, it covers the key workflow: what it produces, how to pass videos, billing implications, immediate task_id, polling via get_depth_map_status, and token refund on failure. It doesn't describe the response JSON structure, but that's not necessary given the status tool and the task_id return.

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 descriptions already explain that video_url can be an external URL or a Switch video id, and duration_seconds is required for external URLs. The description reinforces this but does not add significant new parameter-level detail beyond the schema's own 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 uses a specific verb ('Turn a video into') and clearly defines the output as a depth map, a grayscale video encoding distance. It distinguishes this from sibling tools like get_depth_map_status (status polling) and analyze_video by focusing on depth map generation.

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 explains how to provide input via external URL or own Switch video ids, naming list_my_videos and list_my_assets for retrieving ids. It also specifies when duration_seconds is required and points to get_depth_map_status for polling. It lacks an explicit 'when not to use' but the context is sufficient.

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 and idempotentHint, so no contradiction. The description adds meaningful behavioral context by outlining the exact return payload (model id, display name, brand, credits), which goes beyond what the annotations 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 a single, well-structured sentence that front-loads the action ('Browse') and efficiently packs the resource, scope, return fields, and usage rationale. Every word serves a purpose.

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 no-parameter, read-only browse tool with strong annotations, the description provides complete context: what it does, what it returns, and why to use it. No output schema exists, but the description adequately covers the return information.

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 schema coverage is trivially 100%. The description correctly omits parameter details, and according to the baseline for parameterless tools, a score of 4 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?

Description states the tool browses image-generation models for the user's Switch account and explicitly lists the return fields (model id, display name, brand, credits-per-image). This clearly distinguishes it from sibling video model tools and directly ties it to the generate_image workflow.

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 frames usage as 'before calling generate_image', which provides a clear when-to-use context. It does not name alternative tools for exclusion, but the user's intent to pick a model is well-served by this 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 discloses that each call rebuilds the ZIP, overwrites the stored copy per project, and that the link is private and short-lived. This goes beyond the readOnlyHint=false annotation by explaining concrete side effects and link lifetime.

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: first sentence states the core action and output, second sentence notes the side effect. It is front-loaded, succinct, 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 single-parameter tool with no output schema, the description covers the action, output format and contents, intended use (Photoshop/Figma), and side effects (rebuild/overwrite). It is fully self-contained and leaves no significant gaps.

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 fully describes the only parameter (layer_set_id as the project id). The description adds no new semantic detail about the parameter beyond what the schema already provides, 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 clearly states the tool prepares a private, short-lived download link for a layers project, detailing the ZIP contents (original transparent PNGs and a manifest). This is a specific verb+resource and distinguishes it from sibling tools like get_layer_set or flatten_layer_set.

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 provides clear context that this is for downloading your own layers project for use in Photoshop or Figma, and implies it is not for reading metadata or flattening. However, it does not explicitly name alternatives or state when not to use it, falling 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?

Annotation readOnlyHint=false already indicates a write operation. The description adds non-destructive behavior: 'project stays editable' and repeatability ('you can flatten again'), plus 'composited at full quality'. This enriches behavioral understanding without contradicting annotations. However, it omits any side effects like overwriting behavior or return values, so 4.

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, each adds value: first states the action and outcome, second clarifies non-destructive/repeatable behavior. No fluff. Score 5.

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, no-output-schema tool, the description covers the core action, the library destination, non-destructive behavior, and repeatability. It doesn't elaborate on errors or permissions, but those are not essential for this simple tool. Given the minimal annotations, the description is sufficiently complete for an agent to invoke it. Score 4.

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 covers 100% of the single parameter with a clear description ('The layers project id.'). The tool description does not add additional parameter details, so it meets the baseline for high schema coverage without adding extra meaning. Score 3.

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 verb ('Save') and resource ('your own layers project as a finished picture in your library'), and notes composite from original files. However, it does not explicitly differentiate from the sibling tool 'export_layer_set', so a 4 rather than 5.

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 context for when to use it (when you want a finished picture while keeping the project editable) and notes repeatability, but does not mention alternatives or exclusions. It stops short of explicit when-to-use vs alternatives, so a 4.

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 far beyond the readOnlyHint=false annotation: it explains side effects (generation is saved to library), parameter constraints (text up to 2048 chars, speech_rate, pitch, loudness ranges), voice routing behavior (reference voices, trained clones, presets routed by kind), and dialogue addressing with @Audio1/@Audio2/@Audio3. This gives the agent a clear model of what happens on invocation.

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 paragraph but every sentence carries useful information for a 9-parameter tool. It front-loads the core purpose, then logically covers voice options, alternates, and return fields. It could be slightly improved with bullet points or section breaks, but length is justified by complexity.

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 no output schema, the description explicitly states the return values (playable audio_url, duration_seconds, generation_id) and the side effect of saving to the library. It also covers the full range of input modes (text, saved voice, reference audio, image) and their constraints, making the tool self-contained for the 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?

Although schema coverage is 100%, the description adds significant meaning: voice can be a name or id and is resolved automatically, reference_audio_urls enable multi-voice dialogue via @Audio tags, image_url cannot combine with reference audio, and numeric parameter ranges are clarified. This goes well beyond the schema property 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: 'Generate spoken audio from text,' then lists concrete use cases (narration, voiceover, read-aloud script, multi-voice dialogue). This clearly distinguishes it from sibling generation tools like generate_image or generate_video, which produce different media types.

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 provides explicit usage modes and alternatives: using a saved voice by name, matching from a reference clip, or voicing an image, with the note that image_url cannot combine with reference audio. It also gives operational guidance (resolve voice names yourself, never ask the user for an id) and cross-references the voice tool's list action. It lacks an explicit 'use this instead of X' statement for sibling tools, but internal alternatives are well covered.

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

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

Despite only minimal annotations (readOnlyHint=false), the description discloses important behaviors: auto-routing to models, inline vs. queued processing with progress polling, and persistence of images to Studio library/folder. This adds substantial context beyond the annotation and gives the agent a clear mental model of 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 four sentences, front-loaded with the main action, and every sentence contributes meaningful information (what, models, count behavior, persistence, style). It is concise without sacrificing important operational details.

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

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

For a complex tool with 9 parameters and a rich schema, the description covers the essential workflow: generation, model selection, count handling, persistence, and style integration. It doesn't repeat schema details, and since an output schema exists, return values are already documented. It is sufficiently complete for an agent to understand the tool's primary use.

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 satisfied. The description adds value by explaining count behavior (<=8 vs >8), model auto-routing logic, and style format with concrete examples. It enriches the semantic meaning of key parameters beyond the schema 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 'Generate one or more Switch images,' which clearly states the verb, resource, and scope. This distinguishes the tool from sibling audio/video generation tools and clarifies its core function. Additional details about model auto-routing further specify the 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 provides clear guidance on when to use this tool (image generation) and offers behavioral guidance such as count thresholds (<=8 inline, >8 queue) and model routing logic. It also explains how to use style from apply_* tools, but it doesn't explicitly name alternative tools for audio/video, though those are obvious from sibling names.

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

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

Discloses async rendering (~30-90s), background delivery to library, per-shot task_id return, billing nuance (Seedance 2.5 auto bills 30s up front and refunds unused), face reference verification before charge, and that reference video audio is ignored. These go well beyond the only annotation (readOnlyHint=false) and are not contradicted.

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 well-organized, front-loading purpose then prerequisite and constraints. Every sentence carries useful information, though the single-paragraph format makes it slightly heavy; a few line breaks could improve scannability.

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

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

Despite 18 parameters and no output schema, the description covers the full generation workflow: prerequisite discovery, input selection, async behavior, returned identifiers, and follow-up polling. It wisely defers model-specific details to list_video_models. This is complete for the complexity level.

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?

Input schema already provides 100% coverage with detailed per-parameter descriptions, so baseline is 3. The description adds extra semantics beyond the schema, such as the storyboard default limit ('max 4 by default, hard max 10'), the distinct-shot requirement, and the decision between one shot vs shots array.

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?

Description opens with a specific verb 'Generate Switch video' and enumerates the provider lineup (Kling, Seedance, Switch Video/WAN 2.7, Switch Video Edit, Topaz upscale) and modes (text-to-video, image-to-video, frame-to-frame, motion, omni, reference-to-video, video-edit, upscale). This clearly distinguishes it from siblings like generate_image or generate_audio, leaving no ambiguity about what the 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?

Provides explicit workflow guidance: 'ALWAYS call list_video_models first to pick the right model + mode and see its required inputs' and directs polling via get_video_status or list_my_videos. It also sets constraints ('never repeat one prompt to get copies') and explains single-shot vs storyboard usage, though it doesn't explicitly state when-not-to-use alternatives beyond these companion calls.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds valuable behavioral context: it reports processing while rendering, returns depth_video_url on completion, and confirms token refund on failure. This goes beyond the annotations 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 three sentences, front-loaded with purpose, then usage, then behavior. Every sentence provides necessary information with no 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 polling tool with one parameter and no output schema, the description covers all relevant states: processing, successful completion (with download link), and failure (with token refund). It is sufficiently complete for an agent to use 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 coverage is 100% and the parameter task_id is described as 'The task_id returned by create_depth_map.' The description repeats this context ('Pass the task_id it returned') but adds no new syntax or format details, 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 explicitly states the tool checks depth map renders started with create_depth_map, using a specific verb 'check' and defining the resource type. It clearly distinguishes itself from sibling tools like get_video_status by focusing on depth map renders and referencing create_depth_map.

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: use it with the task_id returned by create_depth_map. It does not explicitly mention exclusions or alternatives, but the reference to create_depth_map and the specific status-checking behavior sufficiently imply when it should be used.

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 idempotentHint=true, so the description doesn't need to restate safety. It adds value by disclosing exactly what information will be returned (layer details, stacking order, visibility, position), giving the agent a clear expectation of the response without an output schema.

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

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

Two concise, front-loaded sentences. The first sentence states the action and result, the second provides usage guidance. No fluff or repetition of schema details.

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

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

Given the low complexity (1 parameter, no output schema, no nested objects), the description fully covers what the tool does and when to use it. The annotations cover safety, and the schema covers the parameter. The description fills the gap by explaining the return payload and workflow context.

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% for the single parameter, with the schema noting the id comes from split_image_into_layers. The description reinforces this by explaining the purpose of retrieving ids ('so you know their ids'), which adds contextual meaning beyond the schema field description.

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 verb 'Open' with a specific resource ('layers projects') and enumerates the returned data (name, description, stacking order, visibility, position). This distinguishes it from siblings like update_layer_set, export_layer_set, and flatten_layer_set, which imply different operations.

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

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

Provides explicit usage context: 'Use this before arranging layers so you know their ids.' This tells the agent when to invoke this tool. While it doesn't mention alternative tools or exclusions, the directive is clear and actionable for the intended workflow.

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 substantial behavioral context beyond the readOnly/idempotent annotations: it details the two groups, explains that alive:false refs are dead and excluded, mentions usable signed URLs, and clarifies that chat attachments are not included. This goes beyond what annotations alone convey, providing essential operational details.

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?

Every sentence in the description earns its place: purpose, usage guidance, dead-ref handling, and chat-attachment exclusion. It is dense but not verbose, effectively communicating complex information in a compact, structured manner 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?

The description is fully complete for a zero-parameter tool with no output schema. It explains the return structure (two groups with signed URLs), usage timing, how to use results with generate_video, and what is excluded. No critical information is missing, and the guidance is actionable.

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 schema is trivially complete. Per the guidelines, a baseline of 4 is appropriate. The description does not need to explain parameters, and it focuses on return semantics instead, which is not required but beneficial given no output 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 reads the user's staged references in Switch Studio and explicitly explains the two returned groups (refs and videoReferences). It distinguishes itself from siblings by mentioning specific contexts like the image-generation reference strip and the Omni/Image video tabs, making it clear which tool to use for staged references.

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

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

Usage guidance is explicit: 'Call this before generate_image or generate_video whenever the user says "use my refs" or refers to images they staged in Studio.' It also provides an exclusion for chat-attached photos and names the alternative tool (upload_media), giving clear when-to-use and when-not-to-use instructions.

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 annotations (read-only, idempotent), it discloses return behavior (status, view_url when finished, error on failure) and polling etiquette. This adds actionable behavioral context without contradicting 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 cover purpose, return values, and usage guidance with no wasted words. 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 covers purpose, return format, error indication, and polling interval. It does not enumerate possible status values or explicitly state that at least one parameter is required, but these are minor gaps for a simple status tool.

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

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

Schema coverage is 100% and already describes both parameters. The description repeats that task_id is from generate_video and job_id is an alternative, adding minimal new 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 checks the status of video jobs using task_id from generate_video or job_id. It is specific and distinguishes the tool from generic status checks by scoping to video jobs.

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 provides explicit polling guidance ('Poll this every ~20s — do not loop rapidly') and clarifies the source of task_id. However, it does not explicitly name alternatives or exclusions for non-video jobs, though the context is clear.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description complements them by disclosing that the tool reports processing status and requires polling. It adds concrete behavioral context beyond the annotations with no contradictions.

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 dense sentences cover purpose, return contents, and polling guidance with no wasted words. The structure front-loads the primary action and then adds necessary details, making it highly 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?

Given the single parameter and no output schema, the description thoroughly enumerates the returned report structure (scores, timeline, sections, metadata, recreation_prompt) and explains the polling behavior. It is fully complete for an agent 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 coverage is 100% but the parameter description is minimal ('The report id to fetch'). The description adds meaningful semantics by specifying the origin of report_id (from analyze_video_report or list_vision_reports) and its role in retrieving the report, going 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 fetches a finished Video Analysis report by report_id, with a specific verb ('Fetch') and resource. It distinguishes itself by referencing analyze_video_report and list_vision_reports as sources of the ID, making 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 explains that report_id comes from analyze_video_report or list_vision_reports, and advises polling every 20-30 seconds while processing. This provides clear usage context without explicitly stating when not to use the tool, so a slight deduct 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?

Beyond the readOnlyHint=false annotation, the description discloses meaningful behavioral traits: it charges credits on create, refunds failed jobs, and returns a branded SwitchApp view_url on status. It also clarifies that the 'best' engine needs no face step, which is valuable operational 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?

The description is dense but well-structured: it front-loads the recommended path, then presents the alternative flow in numbered steps. Every sentence earns its place—no filler or redundancy exists despite the tool's complexity.

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

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

For a complex 13-parameter tool with no output schema, the description is remarkably complete. It covers both workflows, parameter dependencies, timing units, volume controls, credit charges, and the status polling return. An agent has enough context to successfully invoke any action of this tool.

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

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

The input schema covers 100% of parameters, so the baseline is 3. The description adds value by grouping parameters into workflows (e.g., best path needs video_url + sound_file; Kling path needs session_id + face_id + timing), clarifying the base64 data URI format, and noting timing is in milliseconds. This assembly guidance goes beyond the schema's isolated 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 precise verb+resource: 'Lip-sync audio onto one of your videos.' It clearly distinguishes the tool from siblings by focusing on syncing audio to an existing video and lays out the recommended engine path versus the Kling flow, making the purpose immediately evident.

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 steps: a RECOMMENDED action/engine combination and a detailed Kling workflow with numbered actions (identify-face, create, status). It explains when to use each action and which parameters belong to each flow. However, it does not directly compare this tool to sibling alternatives like talking_avatar_video, 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?

Annotations already mark readOnlyHint=true, so the read-only nature is known. The description adds valuable context: it returns counts per status and an array with specific fields, and limits to 'your' tasks. This goes beyond the annotations 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?

Two concise sentences: the first states the core purpose, the second details the return values. No redundant phrasing or 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?

Given there is no output schema, the description compensates by enumerating the returned data (counts per status and task array with field names). It also mentions the default scope ('recent and active'), making the tool's behavior sufficiently 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?

Both parameters have clear descriptions in the schema (limit with default/max, status with allowed values and default), so schema coverage is 100%. The description does not add parameter-specific meaning, but that is unnecessary.

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 ('List') and resource ('generation tasks'), and adds scope ('your recent and active'). It also outlines the return structure, which helps distinguish it from more specific tools like show_generation.

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 viewing the user's own generation tasks but gives no explicit guidance on when to choose this over show_generation or check_job_status. No alternatives or exclusions are mentioned.

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

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

Annotations only provide readOnlyHint=true, but the description adds behavioral context: it returns metadata only, does not display images, and returns newest first. This goes beyond the annotation and is consistent with it. No annotation contradiction.

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 first states purpose and output, the second clarifies what it does NOT do and names an alternative, and the third gives usage context. No waste.

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

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

For a simple read-only list tool with one parameter and no output schema, the description is complete: it tells what is returned, the order, what it doesn't do, and when to use it. No gaps.

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% for the only parameter (count), with default and max documented. The description does not add parameter details, but baseline 3 is appropriate because the schema carries the full burden and the parameter is simple.

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 asset metadata only (id, truncated prompt, model, created date), newest first, and explicitly distinguishes it from show_media by noting it does NOT display images. This is a specific verb+resource+scope that differentiates it from sibling 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 explicit when-to-use and when-not-to-use guidance, including naming the alternative (show_media) and giving an example use case (needing ids/metadata for another tool like move_asset) or a plain text list.

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 and idempotentHint, so the safety profile is covered. The description adds useful context by specifying the returned fields and the library scope, but does not mention potential pagination or hierarchy depth. Overall, it adds meaningful behavioral detail beyond 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 long, front-loaded with the core purpose, and every clause adds value. The first sentence states what it does, and the second explains when to use it, with 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 simple, parameter-less listing tool with good annotations, the description is complete. It states the resource, the information returned, and the recommended usage context. No output schema is needed because the description already lists the output fields.

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 correctly implies that no input is needed, and the empty schema confirms this. Any attempt to explain parameters would be superfluous.

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 'List the folders in your Switch library' with a specific verb and resource, and even details the returned fields (id, name, parent). It is well distinguished from sibling list tools like list_my_assets and list_my_videos by explicitly naming 'folders'.

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 states when to use the tool: 'Use this to find an existing folder before move_asset or create_folder.' This provides direct guidance on the appropriate context and links to related operations, making the usage intent unambiguous.

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, but the description adds meaningful behavioral context beyond that: the ordering ('newest first'), returned fields, and that view_url is only for finished clips. This helps the agent set expectations 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 concise at two sentences, front-loads the core action and result, and avoids redundancy. Every clause adds value, from ordering to the use case.

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?

This is a simple list tool with only two optional parameters, no output schema, and read-only annotations. The description fully covers what is returned, ordering, and intended use, making it complete for this complexity level.

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 provides 100% coverage with descriptions for both parameters (count and status), satisfying the baseline. The description does not add parameter-specific details, but it doesn't need to since the schema is complete.

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 recent Switch videos with a specific verb ('List'), resource ('your recent Switch videos'), and scope ('newest first'). It also lists the returned fields, making it distinct from sibling tools like get_video_status or list_generations.

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 usage context: 'Use this to check whether videos finished and to let the user choose which one they want.' This tells the agent when to use it, though it does not explicitly mention alternatives or when not to use it, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint and idempotentHint, covering safety. The description adds value beyond these by listing the specific content returned (required inputs, aspect ratios, durations, cost) and explaining how the information guides later generation calls.

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

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

Two sentences, front-loaded with the action and resource, with every word adding value. The instruction is clear and free of 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?

As a zero-parameter, read-only listing tool with no output schema, the description fully covers what it returns and when to use it. There is no missing critical information.

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?

This tool has zero parameters, so no parameter documentation is needed. The description appropriately focuses on the output contents instead, which is the relevant semantic information for the agent.

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 the specific verb 'List' and identifies the resource as 'video providers, models, and modes available to your Switch account.' It also details what information is included (required inputs, aspect ratios, durations, cost), clearly distinguishing it from sibling tools like generate_video or explore_models.

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 instructs to call this before generate_video to select a real model and mode, providing clear usage context. It does not mention alternatives or when not to use it, but the directive is specific and actionable.

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 and idempotentHint, so the bar is lower. The description adds useful behavioral context: ordering (newest first) and the exact fields returned, which goes beyond annotations 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?

Two sentences, front-loaded with the main purpose, then a clear call-to-action. Every word earns its place with no redundancy.

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

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

With no output schema, the description covers the return values (fields), ordering, and downstream usage, making it self-sufficient for an agent to select and invoke 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?

The tool has zero parameters, and the baseline for 0-param tools is 4. The description does not need to explain parameters, and it correctly emphasizes the output fields instead.

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 Video Analysis history with a specific verb ('List') and resource, and enumerates the fields returned (report_id, date, status, etc.), distinguishing it from sibling tools like list_generations or get_vision_report.

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

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

Explicitly says to use it to find past analyses, then directs to get_vision_report or video_to_prompt with the report_id, providing clear when-to-use and alternative paths.

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 the description adds meaningful behavioral context: search is metadata-only (id, prompt, date), returns only own assets, and does not display images. This goes beyond the annotation without contradicting it, but omits details like pagination or result ordering.

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

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

The description is three sentences, front-loaded with the primary purpose, followed by scoping and a key exclusion/alternative. Every sentence adds value with 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?

For a read-only search tool with no output schema, the description covers search field semantics, scope limitation, ownership, folder scoping, and the critical non-display behavior with a pointer to show_media. It is complete enough for an agent to invoke and interpret results 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 low (only limit has a description). The description compensates by explaining query as 'prompt substring' and folderId as 'scopes to one folder.' It does not add detail for limit, but limit already has a schema description (Default 20), so the compensation is sufficient.

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: 'Search your library by prompt substring' and clearly delimits scope to metadata only (id, prompt, date). It distinguishes from sibling tools like show_media by explicitly stating 'This does NOT display images.'

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 provides an alternative for when display is needed: 'to show/display results to the user, pass their ids to show_media.' It also sets usage context by noting 'Only your own assets are returned' and the optional folderId scoping, giving clear when-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds context about the response contents (prompts, model, counts, etc.) but does not disclose other behavioral traits like rate limits, permission requirements, or response format beyond the field list. Since annotations cover the main behavioral aspect, a score of 3 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, well-structured sentence that front-loads the core action ('Get the full detail...') and then lists the useful response contents. Every word adds value with no redundancy.

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

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

For a simple lookup tool with one parameter and no output schema, the description is complete: it identifies the resource, the lookup key, the response contents, and implicitly differentiates from list-oriented siblings. No further information is needed for an agent to select and 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% for the single parameter (taskId), with its own description. The tool description reinforces that it's 'by task id' and the schema states the source, which is helpful, but the description adds little beyond the schema's own parameter documentation. Baseline 3 applies.

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

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

The description clearly states a specific verb ('Get'), resource ('one of your generations'), and key dimension ('by task id'), while enumerating the details returned. This distinguishes it from siblings like list_generations (which lists all) and check_job_status (which only checks 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 implies when to use it: when you have a specific taskId and need full generation details. The schema further clarifies the taskId source (from generate_image or list_generations). However, it does not explicitly mention when to use an alternative, such as list_generations for summaries or check_job_status for status only, 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, idempotentHint), the description discloses important behavior: renders a branded SwitchApp media card with a Download action, instructs not to print URLs, and clarifies that asset IDs must be resolved autonomously. These details significantly aid an agent in executing correctly and align 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 longer than minimal but every sentence serves a purpose: front-loaded purpose statement, usage examples, output format note, and video alternative. No redundancy or filler—it is dense with actionable information while remaining readable.

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 (multiple invocation modes, sibling distinctions, output behavior), the description covers all critical aspects: common user phrasings, parameter constraints (max 12), output format, and a clear pointer for videos. With an output schema present, return values are handled elsewhere, so nothing essential is missing.

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

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

Although the input schema already provides 100% coverage for count and assetId, the description enhances this by mapping natural language to parameters ('my last 4 images' → count=4), defining the no-argument default, and clarifying that assetId comes from specific sibling sources. This goes well beyond the schema's static 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 clearly states the tool's function with a specific verb ('Display') and resource ('user's images inline'). It also distinguishes from siblings by explicitly noting that videos are not shown and referencing list_my_videos for that purpose, making the tool's scope 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?

Provides explicit usage patterns: no arguments for 'show me', count for 'my last N images', and assetId for a specific known image. It also names an alternative tool for videos and instructs the agent to never ask for asset IDs, instead resolving them itself—clear guidance on when and how 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?

The description adds substantial behavioral detail beyond the minimal annotation (readOnlyHint=false). It discloses the model version, output format (named/placed transparent PNGs), layer count limit (16), and crucially the billing/refund policy (charged only for layers returned, failed splits refunded). This gives the agent a clear expectation of side effects and costs.

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 redundancy. The first sentence defines the operation and output characteristics; the second gives usage syntax and the billing caveat. Every clause earns its place.

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

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

The description conveys the essential behavioral contract: input requirements, output composition, and financial risk. It does not explain the delivery mechanism or how the resulting layer set can be accessed via sibling tools, but these are not necessary for using 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?

The input schema already covers all three parameters with descriptions (100% coverage), including the 'my last image' alias for asset_id and the meaning of instruction and size. The description restates these but does not add new semantic information 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 and specifically states the tool's function: separating one of the user's own Switch images into editable layers using Seedream 5.0 Pro, producing a base plus up to 16 named and placed transparent PNG layers. It distinguishes itself from sibling layer management tools (export_layer_set, flatten_layer_set) by focusing on the split operation.

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 invocation context: the user must specify an image (asset_id or 'my last image'), optionally an instruction for what to separate, and a size. It also implies an ownership constraint ('your own'). However, it does not explicitly contrast with alternative tools 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 only include readOnlyHint: false, which signals mutation but nothing else. The description adds valuable behavioral context: it says the tool 'renders the combined video with ffmpeg', returns a downloadable URL 'right away', and saves the result to list_my_videos. This goes beyond the annotation and sets expectations for side effects and output. However, it does not mention any potential source-video constraints (e.g., codecs, resolution) or rate limits, so a small gap remains.

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 (3 sentences) and front-loads the core purpose. Each sentence adds distinct value: purpose/ordering, parameter hints, behavior/return, and usage guidance. No fluff or repetition of schema facts beyond what's necessary for emphasis (ordering). It is appropriately sized and perfectly 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?

Given this is a mutation tool with 5 parameters and no output schema, the description covers all essential context: what it does, how to supply inputs (ordered list from list_my_videos), optional parameters, the return value (downloadable URL), and the side effect (saved to list_my_videos). It leaves no major ambiguity for an agent deciding to use or invoke the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds crucial meaning for clip_asset_ids by emphasizing the ORDERED nature and that the first id plays first, plus the hint to get IDs from list_my_videos. It also highlights that orientation, fps, and quality are optional, but doesn't detail all parameters (e.g., project_name) — though the schema already covers those. The added ordering semantics elevate it above baseline.

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

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

The description clearly states the tool stitches multiple videos into one, with a specific verb ('stitch'), resource ('several of your Switch videos'), and outcome ('ONE video, played back-to-back in the order you give'). It also differentiates from siblings by explicitly targeting combine/join/merge/concatenate use cases, which is absent in sibling names like generate_video or analyze_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?

The description provides explicit when-to-use guidance: 'Use this whenever the user wants to combine, join, merge, or concatenate multiple clips into one.' It also references a sibling (list_my_videos) as the source for IDs, giving practical context. No exclusions are needed; the 'whenever' phrasing is unambiguous.

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 substantial behavioral context beyond the minimal readOnlyHint: it discloses the ~1-5 minute render time, that it returns a finished branded video in a single call, that the video is saved to the library, and that it is charged per video. These details are crucial for an agent to manage cost, expectations, and workflow and are not present in 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 concise and well-structured: it starts with the core purpose, then details required/optional parameters, and finishes with timing, invocation model, persistence, and cost. Each sentence contributes unique information without redundancy, making it easy to parse quickly.

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 6 parameters, a nested object, and no output schema, the description covers the key aspects: inputs, optional parameters, behavior (render time, single-call), and consequences (saved, charged). However, it does not describe the exact output format (e.g., video URL or ID) or specify failure/error behavior, leaving minor gaps for an agent to infer.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description reinforces the either/or relationship between script and audio_url and notes the character limit, but it adds minimal new semantics beyond what the schema's parameter descriptions already provide. 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: converting a face photo into a lip-synced talking-head video that speaks text or audio. The verb 'Turn' and specific resource ('face photo' → 'talking-head video') make it unambiguous, and mentions of 'branded video' and 'saved to your library' differentiate it from similar siblings like lip_sync_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?

The description provides clear input requirements: image_url plus either script or audio_url, and lists optional parameters. It gives context on how to invoke the tool correctly, though it does not explicitly state when to choose this tool over alternatives such as lip_sync_video or generate_video, or any 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?

The description adds behavioral context by stating 'Saves immediately through the same checks the Switch workspace uses, so the app shows the same thing.' This goes beyond the annotations (readOnly=false, idempotent=true) by explaining persistence and consistency with the app. It also mentions the ability to reset layers, adding transparency about reversibility.

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, front-loaded with the primary purpose, and includes key behavioral context without redundancy. Every sentence contributes value.

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

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

Given the tool's moderate complexity (two parameters, one nested array), the description covers all major operations and the save behavior. It doesn't explain every edge case, but the schema and annotations fill in the details. Some extra context about ownership or permission is implied by 'your own', but overall it is complete enough for an agent to select and invoke the tool.

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

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

The schema description coverage is 100%, so all parameters are already documented. The description echoes the box format and reset behavior, but adds no new parameter-level information beyond what's in the schema. It does not compensate with extra syntax or usage 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 states the tool arranges a layer set by showing/hiding, moving/resizing, reordering, or resetting layers. It uses the specific verb 'arrange' and identifies the resource as 'your own layers project', which distinguishes it from sibling tools like get_layer_set or flatten_layer_set.

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 it: when you need to arrange layers in a project. It implies usage by stating 'Arrange your own layers project' and adds the nuance that it saves immediately. It doesn't explicitly mention alternatives, but the context is sufficient to differentiate from read-only or export 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 discloses that Switch fetches/decodes the image server-side, stores it, and returns a clean public URL plus new asset id. It clarifies the returned URL is provider-fetchable as-is, with 'no presigned PUT, no curl, no confirm-upload step,' adding value beyond the annotations' readOnly/idempotent 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?

The description is dense but every sentence serves a purpose, front-loading the main action, then parameter options, then usage guidance and exclusions. No wasted words or redundant schema 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?

Despite no output schema, the description explicitly states the return includes a clean public URL and asset id. It provides downstream integration details for generate_image and generate_video, and warns against using get_my_active_references, making it a complete self-contained guide.

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 covers all three parameters, and the description adds the critical relationship that `url` OR `base64` + `mime` are alternative input modes. It also specifies that `mime` is used for base64, complementing the schema with usage constraints.

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 'Upload one image into your Switch library in a single call' with a specific verb and resource. It does not explicitly distinguish from the sibling tool `upload_reference_asset`, but the rest of the description clarifies the unique use case for chat-attached photos.

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 when to use this tool: 'This is THE way to use a photo the user attached in chat as a reference' and gives exact destination parameters for generate_image and generate_video. It also provides an exclusion: 'Do NOT call get_my_active_references for a chat-attached photo.'

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

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

Despite annotations only indicating it is not read-only and not idempotent, the description richly discloses behavioral traits: it returns opaque asset_ids, adds to the active reference strip unless activate=false, describes the two-step presign/confirm_path flow, and notes that face uploads are stored as untouched originals in a private bucket with KYC restrictions.

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 information-dense and structured: it starts with the core purpose, then returns, strip behavior, the preferred presign flow, and a caution about base64. While somewhat long, every sentence contributes value and the key points are 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?

Given 9 parameters and no output schema, the description covers the main operational nuances, including the two-step upload, strip activation, and special handling for audio. It does not document every edge case, but the schema covers parameter-level details, and the description captures the critical integration behavior.

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%, but the description adds meaningful semantics beyond the schema: it explains the end-to-end presign workflow, clarifies that base64/url is only for tiny inline files, and adds context for frame_type ('face' for likeness, KYC-only). This goes beyond the schema 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 clearly states it uploads image/video/audio references into Switch cloud and returns an opaque asset_id. It distinguishes itself from generic uploads by emphasizing reference fields and the reference strip, and it differentiates from siblings like upload_media by its explicit purpose and integration points.

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 usage context: references are for generate_image/generate_video, and it gives explicit guidance on when to use the presign flow ('PREFERRED for real files') vs base64/url ('only for tiny inline files'). However, it does not explicitly mention alternative tools like upload_media 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?

Beyond the annotation (readOnlyHint: false), the description discloses crucial behavioral details: async rendering with polling via get_video_status, billing per second of source clip, and cost implications of 60 fps (double cost). It also specifies that 1.5x scale is allowed and batch limits. This is rich context that aids the agent in managing expectations and costs.

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: purpose, scale options, fps/cost note, model list, batch input format, accepted ID types, async behavior, and billing. It is front-loaded with the primary function and structured logically, with 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?

The tool is complex (5 parameters, async, multiple input forms, billing) and the description covers all key aspects: input sources, batch limits, async polling, cost implications, and model families. No output schema exists, but the description points to get_video_status for status/results, making the workflow clear. It is complete for an agent to select and 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 coverage is 100%, setting a baseline of 3. The description adds value beyond the schema by explaining accepted input forms (Switch job ID, download_url/view_url, public https URL), batching up to 10 clips via videos, and cost nuances (60 fps doubles cost). This enhances the agent's ability to construct correct 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 opens with a specific verb+resource: 'Upscale and enhance one of YOUR videos (or a public https clip) with Topaz.' It clearly states the tool's function and distinguishes it from siblings like generate_video or lip_sync_video by focusing on enhancement of existing video content. The scope is well-defined.

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: it is for upscaling/enhancing existing videos, with batch capabilities and accepted input sources (Switch job ID, URLs). It implies usage for video enhancement rather than generation. However, it does not explicitly name alternative tools or state when not to use this tool, though the purpose is unambiguous.

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=true, but the description adds valuable behavioral details beyond that: it is free to use ('never charges'), it does not consume credits beyond the original analysis, and it converts an existing analysis rather than creating a new one. This financial and operational context is not present in 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 front-loaded with the main purpose and then efficiently covers inputs, cost, prerequisites, and optional parameters. However, it is slightly verbose, repeating the 'free' aspect twice and including extra explanatory phrases like 'reusable generation prompt' that are already implied. Still, every sentence contributes meaningful information.

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

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

The description covers the tool's purpose, input sources, prerequisite, cost, and optional parameters. It does not specify what happens if both report_id and video_url are provided or if neither is passed, but the schema's lack of required parameters could create ambiguity for an agent. Otherwise, it is complete for a conversion tool with no output 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 100%, so the schema already thoroughly documents all four parameters. The description adds a high-level summary of mode and engine ('pass mode to control what the prompt describes, and engine to pick the model format'), but no additional syntax or usage detail beyond what the schema provides. 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 a specific action ('Turn one of your finished Video Analysis reports into ONE reusable generation prompt') and identifies the resource (analysis reports) and output (generation prompt). It distinguishes itself from siblings like analyze_video_report and generate_video. The mention of a {your photo} placeholder adds specificity about what the prompt contains.

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 tells when to use this tool: after a video has been analyzed. It instructs to pass report_id (from analyze_video_report or list_vision_reports) or video_url, and if the video hasn't been analyzed, to run analyze_video_report first. This clear guidance, including prerequisite steps, is exactly what an agent needs to decide when to invoke 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?

The description discloses significant behavioral details beyond the sparse annotations: actions are mutating (create, rename, clone, delete), clone costs 2 credits, create is free and ready instantly, audio clips must be 10–30 seconds, and voice names must be unique per account. It also explains the 'kind' semantics and that names are resolved to ids, making the tool's side effects and constraints transparent.

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 every sentence earns its place; it is front-loaded with the core value proposition and the key rule about resolving names, then structured action-by-action. The density is justified by the tool's many actions and parameters, and there is no redundant filler or repetition of schema field names.

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 all actions, parameter usage, naming policy, relationships to other tools, and cost constraints. It explicitly states what 'list' returns (every saved voice with voice_id, name, kind, ready), but it does not mention return values for create, rename, clone, or delete, and does not describe error conditions. Despite the lack of an output schema, the description is largely complete for an agent to select and 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?

Although the input schema already documents every parameter (100% coverage), the description adds cross-action meaning: voice_id can be a name, audio_url can be the result of upload_media, format defaults to wav, and voice_name uniqueness across the account. It also explains the purpose of parameters in the context of each action, going beyond simple 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 states the tool manages a voice library with a clear verb and resource ('Your saved voices — one tool for the whole voice library'). It explicitly enumerates five actions (list, create, rename, clone, delete) and distinguishes voice kinds (reference, clone, avatar) and how they relate to sibling tools like generate_audio and talking_avatar_video, effectively separating it from siblings.

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

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

The description gives explicit when-to-use guidance: resolve voices by name, call list first if unsure, never ask the user for an id. It also describes each action's trigger scenario (e.g., clone for avatar voices, create from clip via audio_url or audio_base64) and notes that avatar voices drive talking_avatar_video, providing clear context for choosing the right action.

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