framesail AI

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds value by explaining that activating a version affects downstream artifacts and requires subsequent scanning if text differs. It does not contradict any annotations and provides useful behavioral context beyond annotation 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: first states the core action, second provides essential post-usage instructions. It is concise, front-loaded, and contains no superfluous 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?

Given the tool has one parameter and no output schema, the description covers the action, input source, and necessary follow-up actions. It is complete for a simple mutation tool. A minor improvement would be to mention the return value or effect, but it 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?

The only parameter, script_id, is described in the schema with 'ID of the script version to activate, from get_script's version list'. The description reinforces this by mentioning the source of IDs and that save_script creates a version each time. This adds meaning beyond the schema, especially since schema coverage is 100%.

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

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

The description clearly states the tool's action ('Switch the project's active script to another saved version') and specifies the resource (script version). It also explains where IDs come from (get_script's version list) and that save_script creates versions, distinguishing it from sibling tools like get_script and save_script.

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 post-usage guidance: 'Re-run scan_script / rescan_voice_blocks afterwards if the text differs, since downstream artifacts follow the active version.' This clarifies when follow-up actions are needed. However, it does not explicitly state when not to use this tool or compare it to alternatives beyond implied 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?

Adds useful behavioral context beyond annotations: defaults to looping, volume at bed level (~-14 dB), and the need to export to hear. 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, no fluff, purpose first, actionable details. 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?

Covers key behavioral traits and parameter context. No output schema so return not needed. Could mention timeline placement but sufficient for agent 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?

Adds meaning beyond schema: explains library_track_id source, volume dB equivalence, loop duration (whole video), and start_frame interpretation. Schema coverage is 100% but description enriches 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?

Clearly states the tool adds background music from the audio library, with explicit reference to how to find track IDs via browse_audio_library. Distinct from sibling tools like browse_audio_library and remove_music_track.

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 default behavior (loop, bed level volume) and action needed to hear it (re-run export_video). Warns against raising volume without being asked. Lacks explicit when-not-to-use or comparison with alternatives like add_segment_sfx.

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 an important behavioral trait: after attaching, you must run build_scenes to see the effect on the timeline. This adds context beyond annotations, which only indicate non-read-only and non-destructive. It could mention permissions or side effects, but the core behavior is covered.

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 exceptionally concise—two sentences—with no wasted words. It front-loads the core action and follows with essential prerequisites and follow-up steps, making it 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 additive tool with no output schema and high schema coverage, the description covers the main action, prerequisite, and necessary post-processing. It lacks details about error cases or idempotency, but given the tool's simplicity, it is contextually complete enough.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal extra meaning: it restates that library_track_id comes from browse_audio_library, but doesn't enhance understanding of project_id or segment_number 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 action: attaching a sound effect from the audio library to a segment. It specifies the resource (segment) and source (audio library), and distinguishes it from siblings like remove_segment_sfx and add_music_track.

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: it tells the user to find track IDs via browse_audio_library(category='sfx') and to re-run build_scenes to apply changes. It doesn't explicitly state when not to use it, but the guidance is sufficient for correct 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 declare destructiveHint: true; description adds that it is async and requires waiting for a job via await_jobs. This provides additional behavioral context beyond the annotation.

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 short sentences, no redundant information, and front-loads the key action and async nature.

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 async tool, the description adequately covers purpose, usage timing, and post-invocation steps. Slightly lacks detail on what 'style analysis' entails, but sufficient 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 has 100% coverage and describes style_id with context. The description does not add extra semantic detail beyond the schema, so baseline score 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 it re-runs style analysis after input changes, using specific verbs and resource. It distinguishes from siblings like create_style, get_style, and update_style_fields by focusing on triggering analysis asynchronously.

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 mentions 'after changing a style's inputs' as the context for use. Does not explicitly state when not to use, but the context is clear enough.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds blocking behavior, return structure, and timeout logic. No contradictions. Could mention that it does not modify state, but annotations already cover safety.

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: purpose, return value, usage hint. Front-loaded and concise. 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?

Despite no output schema, description explains return {done, jobs} and how to use result (loop). Complete for a blocking tool with clear timeout 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% with good param descriptions. Description adds the timeout_seconds <=50 guidance and implies mutual exclusivity of style_id and project_id (schema already states 'exactly one'). Slight added 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?

Description clearly states it blocks server-side until jobs are done or timeout, and explicitly distinguishes from polling get_workflow_status. Verb 'block' and resource 'jobs' are specific.

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 'use this instead of polling get_workflow_status yourself' and advises calling again if done=false. Provides timeout constraint (<=50s) to avoid client timeout.

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 indicate a safe, read-only, idempotent operation, and the description confirms this by stating 'browse'. It adds context about the return value being track IDs for later 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?

Two concise sentences that front-load the purpose and key differentiator, with no unnecessary 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?

For a simple browse tool with filters, the description sufficiently explains the output (track IDs) and its downstream usage, though no output schema is provided.

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?

All parameters are fully described in the schema (100% coverage), so the description adds minimal additional semantic value beyond summarizing the category 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?

Clearly states the tool browses the audio library for background music and sound effects, distinguishes between 'music' and 'sfx' categories, and explains it returns track IDs for use with add_music_track/add_segment_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?

Specifies category values and output usage, but does not explicitly state when to use this tool over siblings like add_music_track.

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 indicate destructiveHint: true, so the description should ideally explain what destructive action occurs (e.g., overwriting previous timeline state). The description mentions compiling into the timeline but does not disclose potential data loss or overwrite behavior. However, it does not contradict annotations, so it is adequate but lacks additional 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?

Two concise sentences: the first states the purpose, and the second provides pipeline context. No wasted words, and the most critical information is front-loaded.

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

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

With a simple input schema (one parameter), no output schema, and annotations provided, the description adequately explains what the tool does and when to run it. It could have included more details about return values or destructive effects, but it is largely complete for the tool's 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?

Only one parameter (project_id) is present, and the input schema already provides a clear description ('Project ID, as returned by create_project or list_projects'). The description adds no further meaning to the parameter, so it meets 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 explicitly states the tool compiles segments, assets, and voiceover into the editor/render timeline (scenes). It also positions the tool in the pipeline: 'Run after segment assets are complete, before export.' This clearly distinguishes it from sibling tools like 'export_video' and 'generate_segments'.

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 pipeline context ('after segment assets are complete, before export'), which implies when to use it. It does not explicitly list alternatives or state when not to use, but the pipeline order is sufficient guidance among the sibling tools.

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

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

Annotations already indicate destructiveHint=true, so the description reinforces a mutation operation. It adds context on the 'carry_frame' option, explaining its effect. 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 concise sentences: first states purpose and type values, second explains the key option. Every sentence is valuable 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 a 4-parameter tool with no output schema, the description covers the main behavior and key option. Missing details on side effects or return values, but acceptable given schema coverage.

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 already well-documented. The description adds minor elaboration on 'carry_frame' behavior, but does not significantly exceed schema detail. Baseline 3 is appropriate.

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

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

The description clearly states the tool's action: 'Change a segment's visual type' and lists the three allowed types. It distinguishes from siblings like 'split_segment' or 'update_segment_content' by focusing solely on visual type change.

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 (when changing segment type) but lacks explicit guidance on when not to use or alternatives (e.g., 'update_segment_content' might also adjust visuals). No exclusions or context provided.

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 mark destructiveHint=true; the description adds valuable behavioral context: 'Later segments renumber — re-check get_segments before further edits.' This warns of side effects and necessary follow-up, far exceeding annotation 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?

The description is extremely concise: a single sentence with three clear parts (action, parameter, side effect). Every element earns its place, and the most critical information is front-loaded.

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

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

Given no output schema, the description covers the operation, constraints, side effects, and follow-up effectively. It does not mention return value or prerequisites like project existence, but those are covered by parameter descriptions. Overall adequate for a modification 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% with good parameter descriptions. The tool description adds value by emphasizing the adjacency constraint and the renumbering side effect, which are not in the schema. It clarifies the 'keep' parameter options, but the schema also covers them, so the added value is moderate.

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 'Merge a segment with an adjacent one' with specific verb and resource. It provides key details (adjacent requirement, keep parameter) and distinguishes from sibling tools like split_segment and change_segment_type by focusing on merging consecutive segments.

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 indicates when to use (merging adjacent segments) and provides a crucial post-operation instruction ('re-check get_segments'). However, it does not explicitly state when not to use or list alternatives, though the adjacency constraint effectively implies only adjacent segments are valid.

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 all false, so the description carries full burden for behavioral context. It does not disclose the return value (e.g., asset ID), side effects, permissions required, or error conditions. The minimal description 'Manually add' only indicates a write operation, leaving the agent without key behavioral details 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: the first states purpose and context, the second gives key parameter hints. Every word is functional, no filler. Front-loaded with the primary action, making it 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?

The description adequately covers the tool's purpose and key parameter hints, but given the absence of output schema and uninformative annotations, it lacks details on return values, error handling, and prerequisites (e.g., project existence). For a creation tool with four parameters, this is minimally acceptable but incomplete.

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 value by emphasizing that the description parameter should be a 'generation-facing spec' and 'be specific', which is meaningful guidance beyond the schema's generic description. It also reinforces the enumerated values for asset_type. This extra context elevates the score.

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 ('add') and resource ('asset'), specifying that it's for manually adding assets the scan missed. The explanation of asset_type as character/environment/object further clarifies the resource scope. This distinguishes it from sibling tools like update_asset and delete_asset by implying a creation action after automated scanning.

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

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

The phrase 'the scan missed' provides context for when to use: to manually add assets not captured by an automated scan. However, it does not explicitly list scenarios where this tool should be avoided or contrast it with alternatives like update_asset or generate_asset_reference. The guidance is implied rather than explicit.

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

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

Annotations already indicate this is a write operation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds no additional behavioral details beyond the creation action, such as authentication needs or side effects. With annotations present, the bar is lowered; score 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?

Two concise sentences with the action front-loaded. No unnecessary words; 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?

For a simple create tool with only two parameters and no output schema, the description is complete. It explains the channel's role as a container, which is sufficient context for an agent.

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

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

Schema coverage is 100%, so the description adds minimal parameter-specific value. It provides context for the resource being created but does not enhance understanding of individual parameters 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 'Create a new channel' and elaborates that it is 'the container for projects and their reusable styles,' which is specific and distinguishes it from adding to an existing channel.

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 advises using the tool when 'the user wants a fresh creative identity rather than adding to an existing channel,' providing clear context and implicit alternative. However, it does not explicitly mention when not to use or detailed prerequisites.

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

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

Adds context beyond annotations: description seeds script generation, and response includes web_url for sharing. Annotations are consistent (not read-only, not 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?

Two concise sentences, front-loaded with purpose and key guidance. 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?

Covers purpose, parameter usage, and response hint. Lacks mention of error cases but sufficient for a simple creation 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. Description adds meaningful guidance for the 'description' parameter ('seeds script generation'), enhancing semantic 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?

Clearly states 'Create a project' and explains the role of the description parameter, distinguishing it from sibling tools like update_project and list_projects.

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?

Clearly indicates when to use (to create a project) but lacks explicit when-not or alternative tools 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?

Discloses async analysis behavior for references and instant creation for presets. Annotations indicate non-readOnly, non-destructive, which aligns with description. 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?

Well-structured with bullet points, concise yet comprehensive. Every sentence adds value, 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?

Covers creation paths, async behavior, and limitations (file references). No output schema, so return values not explained, but the description is adequate for a creation tool with async patterns.

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 descriptions already cover all parameters (100% coverage). Description adds context: mutually exclusive inputs/presets, structure of values, sources for IDs (list_style_presets, list_channels), and need to await_jobs.

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 'Create a style' and details two mutually exclusive paths (references vs. presets). Distinguishes from sibling tools like update_style_fields and delete_style.

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 explains when to use references (analysis, async) vs. presets (instant). Notes file references require multipart REST endpoint and advises to await_jobs before using the style.

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 aligns with the destructiveHint annotation, but adds no additional behavioral context (e.g., irreversibility, permission requirements). Annotations already cover destructiveness, so no contradiction but minimal added value.

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

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

The description is concise (12 words, one sentence). It is front-loaded and purposeful, though a slight expansion on caveats (e.g., permanent deletion) would improve it without sacrificing conciseness.

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 one-parameter tool with destructiveHint and no output schema, the description is adequate but lacks any mention of consequences or confirmation. It meets minimum completeness but offers no extra helpful 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?

With 100% schema coverage, the description adds value by specifying that the asset_id comes from list_assets, providing practical context beyond the schema's parameter 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 action (delete) and the resource (project asset) with an example ('e.g., one the scan over-extracted'). It effectively distinguishes from sibling tools like create_asset, update_asset, and list_assets.

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 cleaning up over-extracted scans but provides no explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives among many sibling 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?

While annotations already set destructiveHint=true, the description adds valuable detail: it lists exactly what gets destroyed (script versions, assets, etc.) and states irreversibility. No contradiction with annotations.

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

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

The description is extremely concise: two sentences front-load the action and scope, then add consequence and usage guidance. No unnecessary 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 (single required param, no output schema) and the presence of annotations, the description fully covers purpose, behavioral impact, and usage 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 100% coverage with a clear description for the single parameter. The tool description does not add further parameter-level meaning beyond what the schema provides.

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

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

The description clearly states the action 'permanently delete' and the resource 'project and everything in it', including specific elements like script versions, assets, etc. This distinguishes it from sibling tools like create_project or update_project.

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 'confirm with your user first' and emphasizes irreversibility, providing clear guidance on when and how to use the tool. This helps the AI agent avoid misuse.

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 destructiveHint=true. The description adds context (e.g., 'failed analysis experiment') and the rebinding warning, enhancing transparency 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 brief sentences, front-loaded with core purpose and immediate usage constraint. 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?

Simple tool with one parameter; description covers purpose, example, and a critical constraint. No output schema is needed. Slightly missing a note on return value (e.g., success), 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?

Schema coverage is 100% with a concise parameter description. The tool description does not add new semantics for the parameter, so baseline score applies.

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

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

The description clearly states the verb 'delete' and resource 'style', with an example usage ('failed analysis experiment'). It distinguishes from sibling tools like 'set_project_style' by warning against deleting styles in use.

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 not to use' (project default style) and directs to alternative tool 'set_project_style' for rebinding, guiding correct invocation.

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 no safety hints (all false), so description must compensate. It discloses synchronous execution, return format (applied mutations + updated scene), and that it uses the same director chat as the editor UI. While it doesn't detail side effects or reversibility, it gives sufficient behavioral context for typical usage.

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, no filler. Front-loaded with the core action and essential context. 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?

No output schema but description covers return type. Schema covers all params. Lacks error handling details or limitations (e.g., unsupported operations), but is complete enough for a natural-language editing tool with sibling reference.

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. Description adds examples for 'message' (e.g., 'move the caption to the top') and clarifies that 'scene_id' comes from list_scenes, but largely reinforces schema content without deep additional semantics.

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

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

The description clearly states the tool edits ONE scene using a natural-language note, lists specific capabilities (move/restyle/add/remove layers, retime), and distinguishes from the sibling project_director_note for whole video edits. The verb 'edit' and resource 'scene' are precisely specified.

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

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

Explicit guidance: use list_scenes to find scene_ids, and for notes spanning the whole video use project_director_note instead. This directly tells the agent when to use this tool vs alternatives.

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

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

Annotations already indicate non-readOnly, non-destructive, non-idempotent. The description adds that it queues a render and is async, which supplements the behavioral profile. 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 sentences, minimal and effective. The first sentence explains the core action, the second provides async workflow. 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?

No output schema is provided. The description mentions polling and calling get_video_url, implying the final result is a URL, but does not describe the immediate return structure (likely a job ID). Could be more complete about return values.

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 a single parameter project_id that has a clear description. The tool description does not add additional parameter meaning beyond the schema, so baseline score.

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 renders the final MP4 using Remotion, fetching the timeline and queuing the render. It is specific about the resource and action, but does not explicitly differentiate from sibling tools, though the unique purpose is 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?

Provides clear workflow guidance: the call is async, and users should poll get_workflow_status for the video_export job, then call get_video_url. It does not mention when not to use, but the context is well defined.

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, that the job writes image onto asset row, and how to check result. Annotations only indicate non-destructive, non-readOnly, so description adds crucial behavioral 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?

Two dense sentences with no wasted words. First sentence defines purpose, second covers usage and workflow. Well-structured for quick comprehension.

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, prerequisite (before voiceover), async pattern, result checking via await_jobs/list_assets/view_image, and the enforcement by server. For a 4-parameter tool with no output schema, this is fully sufficient.

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 with descriptions for all 4 parameters. Description adds context by referencing asset_id usage from list_assets and the async workflow, slightly improving 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?

Clearly states 'Render an asset's reference image in the channel's art style' with specific verb and resource. Distinguishes from siblings like generate_voiceover and generate_storyboard by explaining it's the visual anchor asset.

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 every asset needs one before generate_voiceover, server enforces it, and recommends firing all jobs then calling await_jobs. Also suggests subsequent steps (list_assets, view_image).

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

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

Annotations already communicate that the tool is not read-only and not destructive. The description adds the async nature and the return of a job_id, which is useful. However, it does not disclose what happens to existing scripts (e.g., versioning, overwriting) or any required permissions, leaving some behavioral gaps.

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 extremely concise: two sentences that convey the core purpose and the async return behavior. Every sentence 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?

Given the tool's complexity (async, 4 parameters, no output schema), the description provides essential information: purpose, async nature, and the polling mechanism. It could mention how to retrieve the final script (e.g., via get_script), but is sufficiently complete for an agent to understand the workflow.

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

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

Schema coverage is 100%, with detailed parameter descriptions (e.g., model default, settings valid keys). The description does not add any additional parameter information beyond what the schema provides, meeting 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 it generates the project's script from a description/concept and the channel's narrative style. It is a specific verb+resource, but does not explicitly differentiate from sibling tools like revise_script or save_script, though the distinction is implicit.

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 indicates the tool is async and advises polling get_workflow_status, but it does not provide explicit guidance on when to use this tool versus alternatives such as revise_script or save_script. Usage context is implied but not fully spelled out.

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 (idempotentHint=true, destructiveHint=false), the description adds key behavioral traits: safe to re-run (skips completed/ongoing assets), async execution with one job per asset (requiring await_jobs), and dependency ordering. This fully prepares the agent for expected 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 comprehensive but slightly lengthy. However, every sentence adds crucial information (cost warning, re-run safety, async nature). It is well front-loaded with purpose and critical warnings, balancing detail with necessity.

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 all essential aspects: usage workflow, cost, subsetting, re-run behavior, and asynchronous execution with await_jobs guidance. It provides sufficient context for an AI 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% with descriptions for all three parameters. The description enriches these by reinforcing the dry_run workflow (show estimate with get_credit_balance) and explaining segment_numbers usage for subset rendering. Adds meaning beyond 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 explicitly states it renders actionable segment assets (images, video clips, overlays) across the project in dependency order. It clearly distinguishes itself from other tools like export_video by focusing on segment-level asset 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 provides explicit usage guidelines: ALWAYS run dry_run=true first, show the estimate alongside get_credit_balance, and require fresh user approval for the real run. It also explains how to render a subset using segment_numbers, offering clear when-to and when-not-to 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?

Discloses async behavior ('returns {job_id}'), duration ('longest LLM step'), and cost implications via asset_mix. Annotations already indicate destructiveHint=true, but the description adds valuable context beyond annotations, 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?

Three concise sentences with front-loaded purpose, then prerequisites, then cost and async note. Every sentence 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 complex async tool with no output schema, the description covers purpose, prerequisites, cost implications, and behavior. Minor omission: does not explain what happens if voiceover is missing (likely error). Still highly complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add syntax or format details beyond what the schema provides; it only gives overall context. No additional parameter-specific semantics.

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

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

The description clearly states the tool's function with specific verbs and resources: 'Plan the full visual storyboard: segments, shot pacing, image/video prompts, overlays, continuation chains'. It distinguishes from siblings like generate_script or build_scenes by focusing on visual storyboard planning driven by director and art 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?

Explicit prerequisites and when-to-use guidance: 'Requires voiceover to exist (timing comes from it). BEFORE calling: confirm the project's asset_mix... video-heavy mixes multiply the later render cost.' Also indicates async nature and that it's the longest step, helping the agent plan 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 indicate readOnlyHint=false (write operation) and destructiveHint=false. The description adds value by disclosing async behavior and explaining that both templates are necessary for segment renders and asset references to work. 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 dense but well-structured, starting with purpose, then importance, then usage, then async note. Every sentence adds value, though slightly long (4 sentences). 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 no output schema, the description adequately explains the outcome (rendered template) and its role in the pipeline, referencing get_style and await_jobs. It covers necessary context for a generation tool, though could briefly mention return value (job ID).

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?

All 4 parameters are described in the schema (100% coverage). The description does not add significant additional meaning beyond what the schema provides. It mentions template_type values but the schema already lists them. Baseline 3 for high schema coverage.

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

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

The description clearly states the tool renders a style template image, distinguishing it as a required step in style setup (not optional). It specifies the verb 'render', the resource 'style template images', and the two template types ('character' and 'environment'). It also differentiates from 'generate_asset_reference' by explaining the relationship.

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

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

Explicit guidance on when to use: run once per template_type for every new style, skip if already present (as shown in get_style). It notes async nature (await_jobs then get_style) and tells to finish both templates before generate_asset_reference. Provides clear when-not-to-use conditions.

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 critical behavioral traits beyond annotations: idempotent-like behavior for gap-filling (safe to re-call), async nature (returns one job per block), and cost implications (never re-bills). Annotations only provide readOnlyHint=false, which does not contradict the description.

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 dense, single paragraph that efficiently conveys all key information: main action, two usage modes, prerequisites, optional parameters, async behavior, and safety. No superfluous words; 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?

Given the tool's complexity (5 parameters, two modes, async behavior, prerequisites) and no output schema, the description provides a complete picture: what it does, how to invoke each mode, safety guarantees, needed setup, and return value (jobs). It even directs to complementary tools for further details.

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 description adds significant context: explains that omitting voice_block_ids fills gaps while passing them triggers regeneration; clarifies that model defaults to the default from list_models; references get_section_template and list_models for valid values of settings and editable_sections. This enriches 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 generates TTS audio for voice blocks, distinguishing between gap-filling mode (without voice_block_ids) and explicit regeneration mode (with voice_block_ids). It differentiates from sibling tools like rescan_voice_blocks and update_voice_block by specifying the exact action and prerequisites.

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 guidance on when to use the tool without voice_block_ids (to fill gaps) and when to pass voice_block_ids (to explicitly regenerate after changes). Emphasizes safety of re-calling (skipping already-generated blocks, no rebilling). Lists prerequisites (voices bound via set_narrator_voice/set_character_voice) and references to other tools for optional parameters.

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 non-trivial behavioral context: mention of BYOK provider billing impact (jobs covered bill 0), which is 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?

Two sentences, front-loaded with purpose, zero wasted words. Every sentence serves a purpose: purpose, usage guidance, and a behavioral nuance.

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

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

For a zero-parameter, no-output-schema tool, the description covers purpose, usage context, and a key behavioral detail. It's nearly complete; could add format of returned info, but not critical.

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?

No parameters exist (100% schema coverage). The description adds value by stating what the tool returns ('current credit balance + plan info'), compensating for the lack of an 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?

'Current credit balance + plan info' clearly identifies the tool's output (verb: get, resource: credit balance). No sibling tool deals with credits, so it's well-distinguished.

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 checking before expensive steps and points to generate_segments dry_run as an alternative for cost estimation, providing clear when-to-use and when-not-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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description reinforces this by explaining the tool is for checking status, not mutating state. It adds useful context about web_url usage and step names, going 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 two paragraphs with no wasted words. Every sentence adds value: first paragraph explains what the tool does and when to use it; second paragraph explains how to use step URLs. Well-structured 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?

Given no output schema, the description fully explains the return value: list of step states, running jobs, next_action, and web_url per step. It also provides guidance on using the URLs, making the tool complete for its purpose.

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

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

The input schema has only one parameter (project_id) with 100% coverage. The description does not add extra semantics for the parameter itself, but the baseline is 3 due to high schema coverage.

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

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

The description clearly states the tool returns 'every pipeline step's state... any running jobs, and a next_action'. It uses specific verbs and resource ('get pipeline progress'), distinguishing it from sibling tools that handle individual pipeline steps or other project 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?

The description explicitly tells when to call: 'when picking up an existing project, after any await_jobs, or whenever you're unsure where a video stands — never guess pipeline position.' This provides clear context and exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by specifying the fetched content (settings, voice config, default style, export URL) 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?

Single sentence is front-loaded with the core action 'Fetch a project row', followed by specific fields. No wasted words; every part is informative.

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 retrieval tool with one well-documented parameter and no output schema, the description sufficiently covers what the tool returns (listing key fields). No additional context is needed.

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

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

Schema description coverage is 100% with clear documentation for project_id. The description does not add additional parameter meaning beyond what the schema provides, 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 'Fetch a project row' with specific fields (settings, voice config, etc.), providing a clear verb+resource. It distinguishes from siblings like list_projects (which lists all projects) and create_project/update_project (which modify).

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 retrieving a single project by ID, with context from the sibling 'list_projects' providing clear differentiation. However, it does not explicitly state when not to use this tool or mention alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that it returns the full text and version list, which gives specific output 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?

Two efficient sentences: first states the action, second provides workflow guidance. 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?

For a simple read operation with one parameter and no output schema, the description covers purpose, usage, and workflow completely.

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 project_id is fully described in the input schema, so description adds no additional meaning. Schema coverage is 100%, baseline 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 the tool reads the active script's full text and version list, and distinguishes it from sibling tools like scan_script and save_script in the 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?

Explicitly explains when to use (before scan_script for review) and describes the expected workflow (get_script -> discuss -> save_script), also implying when not to use.

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, destructiveHint=false, idempotentHint=true. The description adds context that it shows sections marked as locked, which is behavioral info beyond annotations. 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?

The description is two concise sentences. The first quickly explains the core function, the second adds a critical constraint. No unnecessary words; front-loaded with essential 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 single parameter, full schema coverage, and annotations covering safety, the description provides sufficient context. It explains purpose and the locked constraint. No output schema, but the tool's simplicity makes this acceptable.

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?

Parameter 'job' is fully described in schema (100% coverage) with examples. The description adds meaning by listing example job values and linking them to the concept of editable sections, providing context that 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 the tool inspects prompt sections for per-call override, distinguishing it from siblings. It lists the specific verb 'inspect' and resource 'section template', and provides example job names, making its purpose unambiguous.

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

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

The description implies usage context: before a generation job call to check which sections can be overridden. It states that locked sections cannot be overridden, providing a key condition. However, it does not explicitly list when not to use or compare with alternatives among siblings.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by specifying the included contents (status, config, public URLs) 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?

The description is a single sentence that contains all necessary information without any fluff or repetition.

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

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

Despite lacking an output schema, the description adequately conveys what the tool returns (status, config, public URLs). It could be slightly more detailed about the exact structure but is sufficient.

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 both parameters well-described. The description does not add significant 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 it lists assets for a single segment, including specific details like status, config, and public URLs. It distinguishes from similar tools like list_assets and view_image.

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 a practical usage hint (pass public_url to view_image) but does not explicitly state when not to use this tool versus alternatives like list_assets.

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 indicate readOnlyHint=true and idempotentHint=true, which the description does not contradict. The description adds significant behavioral context by explaining the continues_from_segment field and the meaning of null (fresh independent shot), which goes 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 concise, with the first sentence immediately stating the purpose. It consists of two short paragraphs, each adding essential information without redundancy. Every sentence earns its place.

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

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

Given the absence of an output schema, the description adequately explains the key fields returned (narration span, type, duration, creative direction, segment_number, continues_from_segment) and the continuation concept. It provides sufficient context for an agent to understand the tool's output and use it with sibling tools.

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

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

There is only one parameter (project_id) with 100% schema documentation. The description does not add additional semantics for this parameter beyond the schema's description, so it meets the baseline for high 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 title 'List segments' and the description 'List the storyboard's segments' clearly specify the verb and resource. It further distinguishes the tool by explaining that the 1-based segment_number is the universal handle for all segment operations, which sets it apart from potentially similar listing 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 states that the segment_number from this tool is used as a handle for other segment tools, providing clear guidance on how to use the output. However, it does not explicitly state when not to use this tool or offer direct comparisons to alternative 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 aligns with annotations (readOnlyHint=true, destructiveHint=false) but adds no extra behavioral context beyond what annotations provide. It doesn't mention permissions, rate limits, or response format, but since annotations already cover the safety profile, this is adequate.

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-loads the purpose, and includes a practical pointer to a related tool. Every sentence 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 read tool with full schema and annotations, the description is sufficient. It mentions the fields to expect and references a sibling tool for modification, covering the main contextual needs. No output schema exists, but the description implies what is returned.

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 describes the style_id parameter (coverage 100%). The description adds no additional meaning to the parameter beyond what the schema provides, so 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 verb 'Fetch' and the resource 'one style row', listing specific fields (inputs and analyzed fields) and distinguishing itself from siblings like create_style, list_styles, and update_style_fields.

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 indicates when to use this tool (to fetch and review a style row) and mentions fine-tuning with update_style_fields, implying when not to use it (for modifications). It could explicitly state alternatives, but the guidance 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=true, idempotentHint=true, and destructiveHint=false. The description adds that the URL is for the 'most recent completed export,' which is useful context beyond the annotations, but does not disclose potential failure conditions (e.g., missing export).

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 concise sentence that front-loads the core functionality. No unnecessary words. Could be slightly expanded to include usage context, but still 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 the tool's simplicity (one parameter, no output schema), the description provides enough information for an agent to understand the return value (download URL) and the condition (most recent completed export). It is largely complete for its scope.

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 project_id described adequately. The description adds no additional semantic meaning about the parameter; it simply restates the tool's action. 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 it returns a 'download URL for the most recent completed export,' specifying the verb, resource, and scope. This distinguishes it from sibling tools like export_video (which creates exports) and get_pipeline_progress (which tracks progress).

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 no guidance on when to use this tool versus alternatives (e.g., when export is completed, or if no export exists). It only states what it does, leaving the agent to infer usage context from the tool name and siblings.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behaviors. The description adds significant behavioral context: jobs drop out after ~30s, a short list doesn't mean lost work, and the correct way to monitor progress via segment_assets or get_pipeline_progress. 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?

The description is a single, well-structured paragraph with a clear purpose, usage note, and warning. 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 no output schema, the description fully explains what is returned (active/finished jobs, per-segment-asset statuses) and caveats (30s expiry, correct interpretation method). It covers all needed context for correct usage.

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 clear descriptions for both parameters. The description adds context that scope is by project_id or style_id for style analysis, reinforcing the schema's instruction to pass exactly one.

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 active and recently-finished AI jobs and per-segment-asset render statuses, scoped by project_id or style_id. It distinguishes itself from siblings like await_jobs and get_pipeline_progress, which are mentioned as alternatives.

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 'Poll this between steps' and 'Prefer await_jobs over polling this in a tight loop'. It provides guidance on interpreting statuses, including that finished jobs drop out after ~30s and that segment_assets should be used to judge render batches.

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

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

Annotations already indicate readOnly and idempotent. The description adds value by explaining the nested structure of descriptions and the presence of optional reference image and voice_id, going 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 mostly front-loaded with purpose and is structured with clear bullet points. Minor redundancy (e.g., 'surfaced top-level here; the raw row nests it') but overall 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 no output schema, the description adequately explains what each asset contains and the recommended workflow after scan_script. It could mention sorting or limits, but for a list tool it is sufficient.

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%. The description adds explicit enumeration for asset_type ('character', 'environment', 'object') and clarifies project_id's origin, 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 explicitly states it lists project assets extracted by scan_script, and details what each asset contains (description, reference image, voice_id). It differentiates from siblings like create_asset, update_asset, and view_image.

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: use after scan_script, then fix descriptions and generate_asset_reference. It mentions the asset_type filter but does not explicitly state when not to use it or alternative tools.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false. The description adds valuable context about channels owning styles and being containers for projects, which is not provided 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?

Two concise sentences: the first states the direct purpose, the second adds meaningful context without any 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 zero-parameter read-only tool without an output schema, the description is adequate. It explains what a channel is and hints at the relationship to styles, though it could be more specific about 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?

No parameters exist, and schema coverage is 100%. The description does not need to add parameter semantics, so it scores the baseline of 4.

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

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

The description clearly states the tool lists channels and explains that channels own reusable styles, which distinguishes it from sibling list tools like list_assets or list_projects.

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 viewing channels, but does not explicitly state when to use it over alternatives or when not to. However, the context of a simple listing operation makes the usage 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, idempotentHint, and destructiveHint. The description adds context about return fields (display names, credits, settings_schema) and default model behavior, which is beneficial 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 (three sentences) and front-loaded. Every sentence adds value: main action, detail on settings_schema, and default model info. 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 one-parameter tool with no output schema, the description sufficiently explains what is returned (display names, credits, settings_schema) and the default model behavior. Annotations cover safety. 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% and the schema description for the 'job' parameter is clear. The description does not add much beyond the schema, 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 explicitly states the tool lists models for a generation job, including display names, credit estimates, and settings_schema. The verb 'list' and resource 'models' are clear, and the scope is specified, distinguishing it from other list_* 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 indicates when to use the tool (to list models for a generation job) and provides a useful note about the first entry being the default. However, it does not explicitly state when not to use or mention alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by specifying what information is returned (volume, loop, timing), providing 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 sentence of 9 words, front-loaded with the key action and resource. No wasted words, maximizing efficiency.

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 one parameter and strong annotations, the description adequately covers the output fields. However, it does not describe the response structure (e.g., array format), but given no output schema, the description partially compensates.

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

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

Schema coverage is 100% and the description does not add any additional meaning to the parameter beyond what the schema provides. 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 verb 'List' and the specific resource 'project's background music tracks', along with the fields displayed (volume, loop, timing). This distinguishes it from sibling tools like 'add_music_track' and 'update_music_track'.

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 no explicit guidance on when to use this tool vs alternatives. The context is implied through the tool name and sibling list, but no direct usage context 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the agent knows this is a safe read operation. The description 'List projects in a channel.' adds no further behavioral context such as pagination, limits, or ordering. With annotations covering safety, a baseline 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 short sentence with no wasted words. It is front-loaded and efficient. While slightly minimal, it earns a 4 for its brevity and clarity.

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 (1 param, no output schema), the description is incomplete. It does not hint at what the returned list contains (e.g., project IDs, names) or that it returns an array. Without an output schema, the description should provide more context about the return value to be fully helpful.

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% description coverage: channel_id is described as 'ID of the channel whose projects to list, from list_channels or create_channel'. The tool description only restates 'in a channel', adding no new meaning. At high schema coverage, baseline is 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 'List projects in a channel.' clearly states the verb (list), resource (projects), and scope (channel). This distinguishes it from sibling list tools like list_assets and list_channels which target different resources.

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 no guidance on when to use this tool versus alternatives. For example, it doesn't mention that channel_id comes from list_channels or create_channel, or that this is for reading projects as opposed to creating or updating them. Sibling tools include get_project, create_project, update_project, but no comparative context 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?

Annotations already indicate readOnly, idempotent, non-destructive. The description adds the important behavioral detail that output keys are masked (only last 4 characters), which is 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, efficient sentence that conveys the purpose and key detail without extraneous 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?

For a simple list tool with no parameters and good annotations, the description covers the key behavioral aspect. However, without an output schema, the return format is not specified, which is a minor gap.

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

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

No parameters exist in the schema. Schema coverage is 100% trivially. The description does not need to add parameter details, and the baseline for 0 params is 4.

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

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

The description clearly states the tool lists registered BYOK providers and adds a specific behavioral detail (masked to last 4 characters). It distinguishes from sibling tools like 'set_provider_key'.

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

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

No explicit when-to-use or when-not-to-use guidance is provided. Usage is implied by the tool's name and description, but alternatives are not 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, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds value by indicating the output contains composition layers, durations, and layout, but does not elaborate on other behavioral aspects.

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 sentence of 10 words, front-loaded with the action, and contains no extraneous information. Every word 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?

For a simple list tool with one parameter and no output schema, the description adequately covers the return content (composition layers, durations, layout). It is sufficiently complete given the tool's simplicity.

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

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

Schema coverage is 100% and the parameter description in the input schema is clear. The tool description does not add additional meaning beyond what the schema provides, so 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 the verb 'List' and the resource 'scenes', and specifies that it returns composition layers, durations, and layout. It distinguishes from sibling tools like 'get_segments' or 'build_scenes'.

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

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

No guidance on when to use this tool versus alternatives such as 'get_segments' or 'get_project'. The description only states what it does without any contextual usage advice.

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 presets are curated and grouped, includes preview image URLs for art presets with view_image compatibility, and explains how creation works. No annotation 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?

Four dense sentences that are front-loaded with purpose and pack in usage guidance, axis grouping, preview detail, and creation workflow without 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?

Despite no output schema, the description fully explains the return content and how it integrates with other tools, making the agent self-sufficient.

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, the description adds value by detailing the output (labels, descriptions, preview URLs) and how to use the returned data.

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 curated style presets grouped by axis, distinct from list_styles which lists user-created 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?

Explicitly tells when to use (no-AI style creation path), instructs not to choose silently, and directly references create_style with presets parameter as the follow-up.

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 declare readOnlyHint, idempotentHint, and destructiveHint as safe/read-only. The description adds behavioral context by explaining the content of the returned rows (driving generation, holding custom variables). No contradictions. It does not mention rate limits or auth, but annotations already cover safety.

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 action, followed by key details. No unnecessary words or repetitions. Efficient and clear.

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

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

For a simple list tool with one parameter and no output schema, the description adequately explains what is returned (style rows with specific fields) and their importance. It could mention the return format, but the context is nearly 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?

The input schema has one parameter (channel_id) with full description (ID from list_channels). The description mentions 'channel' but adds no additional parameter 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 it lists style rows (variable groups) for a channel and explains what styles contain (art_style, narrative_style, etc.) and their role in generation. This distinguishes it from sibling tools like get_style (single style) or create_style.

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 does not provide explicit guidance on when to use this tool versus alternatives like get_style or create_style. Usage is implied (to retrieve all styles for a channel), but no when-not conditions or alternative references are 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds value by specifying the output includes 'audio status and assigned voices', which informs the agent about what to expect. No contradictions with annotations. The description could mention if the list is paginated or sorted, but it is sufficient.

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

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

The description is a single sentence of 16 words, front-loading the action 'List the project's voice blocks' and immediately providing qualifying details. Every word adds value 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?

Given the tool's simplicity, the description adequately covers the main output aspects (audio status, assigned voices) along with the required parameter. No output schema exists, but the description provides enough context for a basic list operation. Minor omissions like pagination or ordering notes do not significantly hinder completeness.

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 coverage is 100%, with a clear description for the 'project_id' parameter: 'Project ID, as returned by create_project or list_projects'. The tool description does not add additional parameter-level context, 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 uses a specific verb 'List' followed by the resource 'voice blocks' and clarifies they are 'per-speaker narration chunks' with attributes 'audio status and assigned voices'. This clearly identifies the tool's purpose and distinguishes it from sibling list tools like list_assets or list_voices.

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 does not explicitly state when to use this tool or provide alternatives. Usage is implied by the listing nature, but no guidance is given on when not to use it or how it compares to other tools like 'rescan_voice_blocks' or 'list_scenes'. An explicit when-to-use note would improve clarity.

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, signaling safe operation. The description adds value by specifying return fields (id, label, preview audio URL) and the provider selection hint.

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 that front-load the main purpose and provide essential details without unnecessary words. Efficient and clear.

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 (one parameter, no output schema), the description covers what the tool returns, the provider options, and usage hint. It is sufficiently complete for an agent to use 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% with a description for the provider parameter. The description reiterates the options and adds context about matching the project, but doesn't significantly extend 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 lists available TTS voices with specific fields (id, label, preview audio URL). It distinguishes from siblings like list_voice_blocks and set_character_voice by focusing on voice options for providers.

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 guidance to match the project's voice_tts_provider and lists the two provider options. While it doesn't explicitly state when not to use it, the context is clear for a listing 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 behavioral details beyond the annotations: it is synchronous, takes a few seconds per affected scene, returns per-scene results, and requires a subsequent export_video call to see changes. This complements the annotations (all false) by disclosing timing and 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 concise (three sentences) and front-loaded with the essential purpose. Every sentence adds value: scope, behavior, timing, return value, and post-condition.

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 has only 2 parameters and no output schema, the description covers all necessary context: what it does, how it works (routing pass), synchronous behavior, return value, and required follow-up action. 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 coverage is 100%, so the schema already describes both parameters. The description provides example values for 'message' and clarifies the origin of 'project_id', but does not add substantial new 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 states a specific verb ('Apply') and resource ('project-wide director note'), with a clear scope and examples. It distinguishes itself from the sibling tool 'director_note' by emphasizing the project-wide scope, implying the sibling is per-scene.

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 clarifies when to use this tool (for project-wide notes) and implies alternatives (likely 'director_note' for per-scene notes). It also notes the required post-step: re-run export_video. However, it does not explicitly state when not to use it.

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

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

Annotations already provide readOnlyHint=false and destructiveHint=false. The description adds the async nature and job_id return. No contradiction, but it does not disclose what happens to the existing asset (overwrite vs version). The description adds some behavioral 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 two sentences, front-loaded with the main action. It efficiently covers key aspects without unnecessary detail. 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?

Given 6 parameters, 3 required, and no output schema, the description covers the main points thoroughly. It mentions async behavior and parameter overrides. Minor gap: it does not explain whether regeneration replaces or versions the asset, but overall it is fairly complete.

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

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

Schema description coverage is 100%, and the description adds significant meaning: asset_type targets start frame for video segments, editable_sections references get_section_template, model empty uses job default, settings come from list_models. This goes well 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 regenerates a segment's primary image or video with optional overrides, and positions it as the API equivalent of the editor's expert drawer. It distinguishes from sibling tools like create_asset or update_asset by focusing on regenerating the existing primary asset.

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 re-running an asset with different model, overrides, or settings. It mentions async behavior and job_id return. However, it lacks explicit when-to-use vs alternatives like update_asset or generate_asset_reference, though the context is clear enough.

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

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

Annotations already provide destructiveHint=true, and the description states 'Remove', which is consistent. No additional behavioral context beyond the annotation is given.

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, efficient sentence. It could have included a brief usage note, but it is well-structured 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 a simple deletion tool with one parameter and annotations explaining destructiveness, the description is sufficient. No output schema exists, so return values are not expected.

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 a clear parameter description that explains the ID comes from 'list_music_tracks'. The tool description adds no further parameter meaning.

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 'Remove' and the resource 'music track from the project', which distinguishes it from sibling tools like 'add_music_track' and 'update_music_track'.

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 parameter description hints at using 'list_music_tracks' first to obtain the ID, but no explicit guidance on when to use this tool versus alternatives like 'remove_segment_sfx'.

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 destructiveHint=true, so the agent knows it is a write operation. The description adds the note about the optional parameter but does not disclose side effects like whether regeneration is needed or if the removal is reversible.

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 action, followed by a conditional clause. Every word serves a purpose 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 removal tool with no output schema, the description adequately covers the core action and parameter usage. It references a sibling tool for asset discovery. However, it could mention post-removal effects like whether segments need regeneration.

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 value beyond the schema by explaining the condition for using sfx_name: not needed if only one SFX, otherwise required. This clarifies the parameter's real-world usage beyond the schema's 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 'Remove a sound effect from a segment,' using a specific verb and resource. It distinguishes itself from the sibling tool 'add_segment_sfx' by focusing on removal, and the context of segment assets 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 explicitly tells when to use the optional sfx_name parameter: when multiple SFX are attached. It also references get_segment_assets for finding the name. However, it does not provide guidance on when not to use this tool or mention alternatives for clearing all SFX.

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 the tool is async, returns a job_id, and that existing audio is superseded, requiring a follow-up. This adds valuable behavioral context beyond annotations. The description's 'non-destructive' claim refers to assets, consistent with destructiveHint regarding voice blocks.

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 key verb and differentiator, no unnecessary information. 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?

Given the tool's simplicity (2 params, no output schema), the description covers purpose, usage context, side effects, and follow-up steps. It is fully complete for an agent to use correctly.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The tool description adds no additional param details but mentions output format, which is a bonus. 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 verb 're-extract' and resource 'voice blocks', and distinguishes itself from the sibling 'scan_script' by noting it is non-destructive and for use after a script edit.

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 identifies when to use (after a script edit, as alternative to scan_script) and provides a follow-up action (re-run generate_voiceover). Does not explicitly state when not to use, but context is sufficient for agents.

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?

Description discloses synchronous behavior, that it returns {revised_text} but does not save, and that selected_text must appear verbatim. Annotations indicate non-read-only and non-destructive, which aligns with the description. 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 sentences efficiently convey purpose, usage, return value, and saving requirement. No extraneous text. Front-loaded with the core 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?

Given the tool's simplicity (3 parameters, no nested objects, no output schema), the description fully explains what the tool does, returns, and how to persist the result. 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 coverage is 100%, but description adds valuable context: instruction is natural-language, selected_text can be omitted for full script revision, and project_id sourced from create_project/list_projects. It clarifies the exact match requirement for selected_text.

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 clearly states the tool rewrites a passage of the active script using AI in the project's narrative voice, mirroring the in-editor revise UI. It uniquely identifies the action and resource, differentiating from siblings like 'save_script' or 'generate_script'.

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 explains when to use (revise passage or entire script) and how to use selected_text. It notes that the result is not saved and requires a subsequent save_script call. However, it does not provide explicit 'when not to use' scenarios or alternative 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 versioning behavior ('old versions are kept') and notes that assets/voice blocks are not automatically updated, requiring scan_script. This adds valuable context beyond annotations, which are all false and uninformative.

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, no wasted words. The first sentence states purpose and versioning behavior, the second gives a clear next step. Perfectly front-loaded and scannable.

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 save tool with no output schema, the description covers versioning, parameter formats, and post-action requirements. It lacks mention of error cases or permissions, but is sufficient for the tool's 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 coverage is 100%, but the description adds meaning: for 'content' it specifies 'plain prose narration, optionally with scene headings', and for 'project_id' it references return values from other tools. This enriches the schema's 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 saves script text, creating a new version while preserving old ones. It distinguishes from generate_script (which generates from scratch) and get_script (which reads), though it does not explicitly differentiate from revise_script.

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 post-action guideline ('Run scan_script afterwards') but does not specify when to use this tool versus siblings like revise_script or generate_script. The context implies it's for saving edited or original drafts, but lacks explicit when-not 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?

Enriches annotations by explaining destructive behavior: assets are recreated not merged, curated descriptions/images/voices lost. Async return of job_id is disclosed.

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 covering purpose, destructive behavior with alternative, and async return. Front-loaded, 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 essential context: destructive nature, async job return, and high-level output. Lacks details on job completion structure, but sufficient given annotations and schema coverage.

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 3 is appropriate. The description adds no extra meaning to parameters beyond what the schema provides.

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

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

The description uses specific verbs ('Analyze', 'extracts', 'splits') and clearly identifies the resource ('active script'). It differentiates from sibling tool rescan_voice_blocks by recommending it for incremental changes.

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 (first scan) and when not to (re-run preferred rescan_voice_blocks after edits). Also notes async behavior.

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 mutability (readOnlyHint=false) and idempotence (idempotentHint=true). The description adds the behavioral context that this binding is a prerequisite for generate_voiceover, which is useful but not extensive. 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 two sentences, directly addressing the purpose, prerequisites, and sibling differentiation. Every sentence is necessary and succinct.

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 output schema), the description covers the prerequisite calls (list_voices, list_assets), distinguishes from narrator, and explains the tool's role in the pipeline. It could mention what happens if voice_id is invalid, but overall complete enough.

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 clear descriptions linking to list_assets and list_voices. The description adds a note about matching the provider, which is already in the schema. Overall, the description adds minimal extra 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 it binds a TTS voice to a character asset, distinguishes from set_narrator_voice, and connects to generate_voiceover. It uses specific verb+resource and explicitly differentiates 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 indicates this tool is required before generate_voiceover for every character with dialogue and that narrator voice is separate. It also references list_voices for IDs. While it doesn't explicitly state when not to use, it provides clear context and prerequisites.

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

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

Annotations already provide idempotentHint=true and destructiveHint=false. Description adds sequencing context (prerequisite for generate_voiceover) but no extra behavioral 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?

Two concise sentences, front-loaded with key purpose and usage. No extraneous 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?

Covers purpose, usage, and dependencies on list_voices and set_character_voice. No output schema, but for a setter tool this is adequate. Minor omission: no mention of return value or error conditions.

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?

Parameter descriptions in schema are thorough (100% coverage). Description does not add new parameter info beyond what schema provides.

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

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

Describes setting the narrator TTS voice, required before generate_voiceover for narration. Distinguishes from sibling set_character_voice by noting character voices are separate.

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?

States required before generate_voiceover when script has narration. Suggests browsing IDs with list_voices and clarifies character voice is separate.

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 declare idempotentHint=true and destructiveHint=false, indicating a safe, non-destructive mutation. The description does not add behavioral details beyond 'set the default style'—missing effects like whether it triggers regeneration or what happens to the previous default.

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

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

Two sentences, front-loaded with the core action, 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?

For a simple mutation tool with well-documented parameters and annotations, the description fully covers what an agent needs to use it correctly: purpose, when to use, and parameters are clear from 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 both parameters described. The description merely echoes schema hints (e.g., 'from create_style or list_styles'), adding no new meaning beyond what the schema already provides.

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

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

Description has a specific verb ('Set'), resource ('project's default style'), and clarifies what that means ('the style whose art/narrative/director fields drive its generations'). It distinguishes from siblings like create_style and list_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?

Explicitly states when to use: after create_style or to switch between channel styles. Provides clear context but does not explicitly mention when not to use or alternatives beyond the immediate ones.

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

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

Annotations already indicate the tool is idempotent and not destructive. Description adds that the key is encrypted at rest and that usage of the key incurs 0 credits, providing useful behavioral context beyond what annotations convey.

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

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

Two sentences, front-loaded with purpose and key constraints, no fluff. 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?

For a simple registration tool with no output schema, the description includes plan requirement, encryption detail, credit saving benefit, and a list of providers. All essential information is covered.

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 both parameters described. Description repeats the schema's info about encryption and provider list without adding new meaning, 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?

Description clearly states it registers a BYOK provider API key, lists the supported providers, and distinguishes from list_provider_keys sibling by specifying that it's for adding a key.

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?

Description explicitly states 'BYOK plan only' as a condition, and explains that jobs using this key charge 0 credits. While it doesn't mention alternatives for non-BYOK plans, the guidance is clear for the intended use case.

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 idempotency and non-destructiveness. The description adds valuable behavioral context: the continuation reference is applied at generation time, so image regeneration is necessary. It also clarifies the number format (1-based) and clearing mechanism. 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 main action, and includes key details (number format, clearing, regeneration). Every sentence adds value without redundancy. It is efficiently structured for an AI agent 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?

Given the tool's simplicity, 3 parameters, full schema coverage, and annotations, the description covers the core concept, the necessary regeneration step, and clearing behavior. It does not mention return values or error conditions, but with no output schema, this is acceptable. It is sufficiently complete for an AI agent to use 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%, with each parameter having a description. The tool description largely repeats the schema's explanation for 'continues_from' and adds no new meaning for 'project_id' or 'segment_number'. While it provides the broader context of why parameters are used, it doesn't go beyond the schema's detail, 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's purpose: setting a segment's image to continue an earlier segment's frame. It uses specific terminology ('continues_from'), distinguishes from other segment tools by focusing on continuation links, and explains the effect. The verb 'set' and resource 'segment continuation' are specific and 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 clear context: it says the link is settable after the fact, explains how to clear it with 0, and instructs to regenerate the image afterward. However, it does not explicitly state when not to use this tool or compare it directly to siblings like 'update_segment_content' or 'change_segment_type', leaving some ambiguity for an AI agent. Nevertheless, the usage intent 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 mark destructiveHint: true, but the description adds critical behavioral context: inherit_index preserves creative data for one part, and resulting segments renumber. 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: first states the operation, second explains inherit_index, third warns about renumbering. No unnecessary words, informative 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?

Covers key behavioral aspects (inheritance, renumbering) for a tool with 4 well-described parameters. No output schema, but description hints that segment numbers change, prompting re-fetch. Adequate 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?

Schema description coverage is 100%, but description adds clarity: offsets_ms are in ms from segment start, ascending, 1-3 cuts; inherit_index default and purpose explained. Adds value beyond raw 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?

Description uses specific verb 'Split a segment at the given time offsets', specifies the resource (segment), and clearly differentiates from sibling tools like combine_segments by detailing the number of cuts and resulting parts.

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?

Description explains when to re-check segments after splitting and mentions inherit_index for choosing which part keeps original data. It does not explicitly exclude alternatives, but the sibling list includes combine_segments, making context 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?

The description adds value beyond annotations by noting the need to regenerate the reference image after visual changes. Annotations indicate mutation (readOnlyHint false) and the description reinforces this with a practical consequence.

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

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

Two sentences with zero wasted words. The first sentence states the core purpose, the second provides an important behavioral note. Ideal 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?

The description covers the essential purpose and one key behavioral implication. For a simple mutation tool with no output schema, it is nearly complete, though it could mention what happens to unspecified fields (handled by schema defaults).

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 description adds no new information beyond what the parameter descriptions already provide. The mapping from action to parameters is implicit but clear.

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 specific verbs ('rename', 'rewrite') and clearly identifies the resource ('asset'). It distinguishes from siblings like create_asset and delete_asset by stating the action as modification.

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 states when to use the tool (to rename/rewrite description) and provides a follow-up condition (regenerate reference image if look changed). However, it does not explicitly mention when not to use or name the alternative tool for regeneration.

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 idempotent and non-destructive behavior. Description adds that changes take effect at next export and no rebuild is needed, which is helpful but does not reveal additional side effects or requirements 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 deliver all critical information: purpose, usage guidance, and timing. No filler or redundant wording. 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 the simple mutation (merge with no rebuild), the description adequately covers the effect and prerequisite reading. No output schema exists, but the description does not specify return value, which is a minor gap. Still, it is fairly complete 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?

Schema coverage is 100%, baseline is 3. Description adds value by explaining 'caption_config' is a partial merge patch, listing example keys (enabled, styling), and directing to get_project for current values. This enriches the schema 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?

Description clearly states the tool merges a patch into the project's burned-in caption config, using specific verb 'merge' and resource 'caption config'. It distinguishes from siblings like update_project by mentioning 'burned-in', but does not explicitly contrast with similar 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 explicit guidance to read current value from get_project before calling, and notes that changes apply at next export with no rebuild needed. Does not cover when not to use this tool or list alternatives, but offers clear context.

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