Avocado AI

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by detailing the return data (credits, tier, generation capability), which is not covered by annotations.

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

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

The description is a single, clear sentence that conveys all necessary information without extraneous words.

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 lacking an output schema, the description covers the return values adequately. For a simple read tool with no inputs, this is 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?

With zero parameters and 100% schema coverage, the description does not need to explain parameters. It provides no further detail but also has no gaps.

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 checks credit balance and specifies what it returns (credits, membership tier, what can be generated). It is distinct from sibling tools like generate_image, which consume credits.

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 when to use the tool (to check credit balance) but does not explicitly state when not to use it or provide alternatives. It implies usage before generation but lacks direct guidance.

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

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

The description adds significant behavioral detail beyond the annotations: it specifies return values (status, URLs, error details, inline image blocks), polling guidance, and typical durations. No contradiction with annotations (readOnly, idempotent, non-destructive).

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 concise paragraph that front-loads the critical usage instruction. It could be structured with bullet points for improved readability, but it efficiently conveys all necessary 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?

Given the tool's simplicity and lack of output schema, the description fully explains the return structure, behavior (polling), and typical timings. It covers all essential information 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?

The single parameter jobId is fully described in the schema. The description repeats the same information without adding new semantics. With 100% schema coverage, 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 checks the status of generation jobs and retrieves results. It explicitly mentions the generation tools it follows (generate_image, edit_image, generate_video) and what it returns, distinguishing it from siblings that create 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?

The description provides clear when-to-use instructions ('always call this tool after...'), what to pass (jobId), and retry behavior with time estimates. It doesn't explicitly list when not to use, but the context is sufficiently 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 are minimal (readOnlyHint=false, destructiveHint=false). The description adds critical behavioral context: it creates but does not run flows, validates sockets, aligns models, and returns id/URL. This far exceeds what 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 long but well-organized with sections: purpose, design principles, hard rules, model menus, node types, edge hints, and examples. Every sentence adds necessary information; no wasted text.

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

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

Given the complexity (numerous node types, models, edge rules, and constraints), the description is fully complete. It includes five detailed examples covering common patterns, and explains return values despite 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 coverage is 100% but the description adds enormous value: valid model ids, voice names, node type purposes, edge handle hints, and example parameter values. It explains the structure of nodes and edges in detail, making the schema meaningful.

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 flow with a node-graph pipeline and returns its id and URL. It distinguishes itself from siblings (single media tools) by specifying it designs full pipelines.

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 extensive usage guidance: when to use (creative goals), design principles (multi-stage, branching, parallel tracks), hard rules (node types, edge compatibility, step labels), and explicit contrast with running flows. Examples further clarify usage.

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

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

Annotations are minimal (readOnlyHint: false, destructiveHint: false), so the description adds valuable context: it creates an empty board and returns the id and URL. 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?

Two concise sentences that are front-loaded with the key purpose and return information. No unnecessary words or 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 creation tool with 1 optional parameter and no output schema, the description adequately explains the action and return values (id and URL). Could mention error handling or authorization but not essential.

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 has 100% coverage with a description for the only parameter (title). The description does not add extra meaning beyond what the schema already provides, meeting the baseline for high schema coverage.

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

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

The description clearly states the verb 'Create', the resource 'new empty Avocado AI storyboard', and the return values (board id and direct URL). It effectively distinguishes from sibling tools like 'list_storyboards' and other creation 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 implies usage for creating a storyboard but does not explicitly guide when to use it versus alternatives like 'generate_image_to_storyboard' or 'generate_video_to_storyboard'. No exclusions or prerequisites 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by listing what the tool returns (capabilities, supported models, pricing, etc.), providing context beyond 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 with three sentences. It front-loads the purpose and adds usage scenarios efficiently. Could be slightly more streamlined, but overall well-structured.

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

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

Given the tool's simplicity (no parameters, no output schema), the description covers all necessary context: purpose, when to use, and what information is returned. Annotations provide safety cues. 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?

Input schema has zero parameters with 100% schema coverage, so baseline is 4. The description does not need to add parameter information, and it correctly focuses on the tool's function.

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

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

The description clearly states the tool's purpose: describing Avocado AI, its capabilities, and offerings. It specifies the verb 'Describe' and the resource 'Avocado AI', and distinguishes from siblings by being the only tool for general platform info.

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 (when user asks about Avocado AI, wants available tools, or is deciding to sign up). It doesn't specify when not to use, but for a non-ambiguous tool this 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 are minimal (no safety hints), but the description fully compensates by disclosing the async job pattern, the fact that it mutates an existing image, and credit costs. 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 a single well-structured paragraph, front-loaded with purpose, then input requirements, async behavior, and model options. Every sentence is necessary and 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 7 parameters, 1 required, no output schema, and no nested objects, the description covers all necessary context: input selection, async return, model differentiation, and quality behavior. The agent can invoke correctly without 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 coverage is 100%, so baseline is 3. The description adds crucial semantics: mutual exclusivity of file_id and image_url (not in schema), credit costs per model, and quality tier behavior. This justifies a 4.

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

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

The description starts with 'Modify an existing image,' which clearly states the verb and resource. It distinguishes from siblings like generate_image and prepare_image_upload by specifying input sources and 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 provides explicit when-to-use guidance: exactly one of file_id or image_url, no base64, steps for chat-attached vs URL images, and the async workflow with check_job. It also explains model selection.

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

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

The description discloses async behavior, typical completion time (10-60 seconds), and credit cost (1-6 per image). It also explains that the image is rendered inline via check_job. Annotations are all false, so no contradiction, and the description adds valuable context 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 a single paragraph with clear front-loading: first sentence states purpose, then async flow, follow-up tool, model listing, and cost. Every sentence adds value without redundancy.

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

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

Given the tool's async nature, multiple parameters, and cost model, the description covers the essential workflow and constraints. It explains what to do with the jobId and mentions inline rendering. Minor omission: no mention of rate limits or failure scenarios, but overall complete for typical 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?

Schema coverage is 100%, providing baseline 3. The description adds value by explaining credit costs for quality tiers, clarifying that quality only applies to 'gpt-image-2', and recommending descriptive prompts. This goes beyond the schema's 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 generates an AI image using Avocado AI, and explains the async behavior (returns jobId, completes in 10-60 seconds). It distinguishes itself from sibling tools like check_job (for retrieval) and edit_image (for editing).

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 advises using check_job to retrieve the result and running models_list to see available models. It also mentions cost and time. However, it does not explicitly state when not to use this tool versus alternatives, though sibling tools provide 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?

Discloses async behavior with placeholder drops and webhook swaps, cost implications (1-6 credits), and the need for a page refresh. This adds context beyond annotations (readOnlyHint=false, destructiveHint=false), with no 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?

A single paragraph that front-loads the main purpose, then explains mechanism, prerequisites, user experience, and costs. Each sentence adds value, though slightly dense; could be split for readability.

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?

Covers key aspects: behavior, prerequisites, UI impact, and cost. However, lacks output/return value description and error handling, which would be helpful given 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 coverage is 100% with descriptions. Description adds meaning to num_images (one placeholder per image) and aspect_ratio (controls placeholder shape), enhancing understanding 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 generates an AI image and places it on a storyboard, distinguishing it from sibling tools like generate_image (no storyboard placement) and generate_video_to_storyboard (video version).

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 advises to use list_storyboards or create_storyboard first to obtain the storyboard_id. Implicitly differentiates from generate_image for standalone generation, but does not explicitly 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?

Discloses credit consumption and persistent storage behavior (saved to Music Studio), adding value beyond the annotations which only indicate non-destructive/non-readOnly. 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?

Three concise sentences with no redundancy. The first sentence immediately clarifies the tool's purpose, and subsequent sentences add necessary constraints without verbosity.

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 lacking an output schema, the description adequately explains the outcome (track saved to Music Studio) and the cost model, making the tool's behavior fully understandable for invocation.

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

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

Schema description coverage is 100%, and the description does not add significant new meaning beyond the parameter descriptions already present in the schema. Example provided in schema, so baseline score 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 'Generate AI music' and details the creation of original tracks from text prompts, clearly distinguishing it from sibling tools like generate_sfx or generate_speech.

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 concrete constraints on duration (30s-5min) and cost (4 credits per 30s block), along with the output destination (Music Studio URL). While it doesn't explicitly state when not to use, the context is sufficient for decision-making.

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 (all false), the description adds important behavioral details: credit cost per 5-second block, duration limits, and where the effect is saved (Music Studio URL).

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, front-loaded with the main purpose, then constraints and cost. No fluff.

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

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

Covers purpose, parameters, cost, and destination. However, with no output schema and sibling tools including check_job, it likely returns a job ID asynchronously, but the description omits this, which is a significant gap for an agent.

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

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

Schema coverage is 100%; description adds context about purpose of duration (1-22 seconds) and prompt influence (default 0.35) via examples, plus cost and saving location, enhancing interpretation.

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 generates AI sound effects from text prompts, distinguishing from sibling tools like generate_music or generate_speech by specifying short sound effects and saving to Music Studio.

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 short sound effects (1-22 seconds) and mentions credit cost, but does not explicitly say when to use this tool versus alternatives or provide exclusion criteria.

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, the description adds cost per character and where the audio appears, which are useful behavioral details not present in 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 core purpose, then cost and result location. No wasted words.

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 input schema and no output schema, the description covers the major aspects: what it does, cost, and where the result appears. Missing error or speed details but 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?

With 100% schema coverage, the baseline is 3. The description adds cost context but does not add new parameter-level meaning beyond the schema's 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 converts text to speech using Avocado AI, mentions multiple voices and languages, and distinguishes from siblings like generate_music or generate_sfx.

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 (text-to-speech) but does not explicitly provide when-not or alternatives, leaving the agent to infer based on sibling tool names.

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

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

Beyond neutral annotations, the description discloses render time (2-10 minutes), polling mechanism ('inline result card polls for completion'), pricing (per-second, model-dependent), and prerequisite workflow (upload image first). This sets accurate expectations for the agent.

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: starts with purpose, lists models with details, then prerequisites, timing, pricing. While long, it front-loads key information and avoids redundancy. Could be slightly tighter but is effective.

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, 100% schema coverage, and no output schema, the description covers all essential aspects: model selection, parameter usage, prerequisites, timing, pricing, and polling behavior. It leaves no significant gaps for an agent to misuse 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?

With 100% schema coverage, baseline is 3. The description adds extra meaning: grouping models by capability, explaining fast_mode as legacy, clarifying resolution relevance per model, and noting aspect_ratio and generate_audio scope. This enhances understanding 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 'Generate an AI video' and lists specific models with their modes (text-to-video vs image-to-video). It distinguishes this from sibling tools like generate_image or generate_speech by focusing solely on video generation, making 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 provides detailed guidance on when to use each model (e.g., seedance requires image, Kling variants support both), prerequisites (prepare_image_upload for images), and constraints (duration bounds, resolution limits). It lacks an explicit comparison to siblings, but the purpose itself naturally guides 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?

Discloses that a placeholder is dropped immediately and the recovery hook swaps it after 2-10 minutes. Notes that refresh may be needed for live update. Annotations don't contradict; description adds rich behavioral context beyond what 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?

A bit lengthy but well-structured with front-loaded main action. Every sentence adds necessary information. Could be slightly trimmed, but 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?

Covers all essential aspects: prerequisites (storyboard_id, image upload), model selection, duration bounds, pricing, and output behavior (placeholder + replacement). Despite no output schema, the description fully informs the agent of what to expect.

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 has 100% coverage of parameter descriptions, but the description adds significant value: explains model variants in detail, per-model duration bounds, difference between file_id and image_url, and defaults. This helps the agent understand parameter constraints and relationships.

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

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

Clearly states it generates an AI video and places it on a user's Avocado AI storyboard. Distinguishes from siblings like generate_video and generate_image_to_storyboard by specifying the placement on storyboard. Uses specific verb 'Generate' and resource 'video to storyboard'.

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 tells the agent to first use list_storyboards or create_storyboard to obtain storyboard_id. Provides guidance on when to use image-to-video vs text-to-video, and that for image-to-video one should call prepare_image_upload first. Also warns about refresh if the tab is open.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description's 'Get step-by-step instructions' aligns with these hints but adds no new behavioral context beyond what 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 two sentences, with the first stating the core purpose and the second providing usage context. It is concise with no redundant or unnecessary 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?

Given the tool's simplicity (one optional parameter, no output schema), the description fully covers purpose, usage, and context. No additional details are needed for an agent to correctly invoke it.

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

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

The single parameter 'client' is fully documented in the schema with enum values and description. The tool description does not add additional meaning or behavior details for the parameter, so it meets the baseline for 100% schema coverage.

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

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

The description clearly states the tool provides step-by-step instructions for connecting to Avocado AI via MCP. It specifies the exact scenarios (sign up, authenticate, connect) and lists example clients, making it distinct from sibling tools which are primarily generation and editing 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 explicitly says 'Call this when a user wants to sign up, authenticate, or connect Avocado AI to their AI assistant', giving clear when-to-use guidance. It does not list exclusions, but the context of sibling tools 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 indicate readOnlyHint=true and destructiveHint=false. The description adds value by specifying the scope (owned and shared) and the exact fields returned, which goes beyond 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 the action and resource, followed by output details and usage guidance. No superfluous words.

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 simplicity (no parameters, no output schema), the description fully covers purpose, output, and usage. Annotations handle safety. No missing elements.

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 zero parameters and 100% schema coverage, the baseline is 4. The description does not need to explain parameters, but it compensates by describing the output structure, aiding understanding.

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), the resource (storyboards), and the returned fields (id, title, last-updated time, thumbnail, URL). It distinguishes itself from sibling tools like create_storyboard, which create rather than list.

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 let the user pick an existing board.' It does not provide explicit exclusions or alternatives, but no alternative listing tool exists among siblings, making the guidance adequate.

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 behavioral burden is low. The description adds context about return content but no additional behavioral traits beyond what 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?

Three sentences, front-loaded with verb and resource, no redundancy. Every sentence adds 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?

The description explains what is returned (slugs, names, costs, descriptions) despite no output schema. It mentions the optional parameter implicitly via 'all available'. Lacks details on pagination or filtering behavior but sufficient for a simple list 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 has 100% coverage for its single parameter (category). The description does not add extra meaning beyond the schema's description, 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 states the tool lists all available AI image generation models, specifies the return fields (slugs, names, credit costs, descriptions), and differentiates from sibling generation tools by being a list/retrieval 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 a high-level usage context ('help users pick the right model') but does not explicitly state when not to use or mention alternative tools. No sibling comparison is given.

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 thoroughly discloses the tool's behavior: it returns a signed URL and file_id, requires subsequent steps (widget upload or curl command), and warns that downstream tools fail with raw bytes. Annotations are minimal (no read-only, destructive hints), so the description carries the full burden and does it well.

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 comprehensive but slightly lengthy; however, every sentence adds critical information for the workflow. It is front-loaded with the mandatory nature and clearly orders steps. Could be slightly more concise, but the information density justifies the length.

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 (preparation step without output schema), the description is complete: it covers the return values, post-usage steps, how to handle the upload in different environments, and prerequisites. No gaps in 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?

The input schema already has clear descriptions for 'purpose' and 'mime_type' with enums and defaults. The description adds value by explaining why each parameter matters (purpose controls downstream tool nudging) and emphasizing defaults. Schema coverage is 100%, so the description enhances rather than replaces schema info.

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 is the mandatory first step for uploading images for editing or video generation, distinguishing it from sibling tools like edit_image and generate_video. It specifies that it returns a signed PUT URL and file_id, providing a clear 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?

Explicitly says this is mandatory when the user attaches an image and wants to use edit_image or generate_video. It explains that downstream tools do not accept base64 and will fail if called directly, providing clear guidance on when to use this tool and why alternatives won't work.

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