framesail

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

Annotations already declare this is not read-only and not destructive, with idempotentHint true. The description adds meaningful behavioral context beyond the annotations: switching the active version affects downstream artifacts, and post-activation rescans may be required. This informs the agent about side effects and necessary follow-up actions.

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

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

The description is two sentences with no filler. The primary action and parameter source are front-loaded, while the post-activation guidance is provided as a necessary caveat. Every clause earns its place.

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

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

For a single-parameter activation tool with no output schema, the description covers the action, the source of valid IDs, the relationship to sibling tools, and the downstream consequences. The agent has everything needed to decide when and how to invoke it correctly.

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

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

The schema already fully describes script_id, so baseline is 3. The description adds extra meaning by explaining the lifecycle of version IDs: each generate_script run creates one, and save_script edits the active version in place. This helps the agent understand what the parameter refers to beyond the literal schema 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?

The description states a specific verb and resource: 'Switch the project's active script to another saved version.' It distinguishes itself from related tools by explaining that generate_script creates versions and save_script edits the active version in place. The purpose is unambiguous and well differentiated.

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 the agent where version IDs come from ('ids come from get_script's version list'), how versions are created versus edited, and what to do after activation ('Re-run scan_script / rescan_voice_blocks afterwards if the text differs'). This provides clear usage context and routes the agent away from confusing it with generate_script or save_script.

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 (readOnlyHint=false, etc.), the description adds key behaviors: default loop and volume with dB equivalent, bed level under narration, and the need to re-run export_video to hear. It includes a warning not to raise volume without being asked.

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 front-load the action and prerequisite, then explain defaults and side effects. 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 and no output schema, the description covers the essential usage: what it does, defaults, and the need to export to hear. It lacks details on error conditions or adding multiple tracks, but overall provides sufficient context for correct invocation.

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

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

Schema coverage is 100%, but the description adds significant meaning: explains the default volume as bed level with dB conversion, clarifies the loop behavior, and ties library_track_id to browse_audio_library. 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 the verb 'Add' and the resource 'background music to the project', with a direct link to browse_audio_library for finding track IDs. It distinguishes itself from sibling tools like remove_music_track and update_music_track by its action.

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 prerequisite (find track IDs with browse_audio_library) and practical tips (default loop and volume, re-run export_video to hear). However, it does not explicitly contrast with alternatives like update_music_track or when not to use this tool.

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

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

Annotations are minimal (destructiveHint=false), so the description adds value by noting the prerequisite (track ID from browse_audio_library) and the post-requisite (build_scenes). It does not disclose whether attaching sound effects is additive or replaces existing ones, but the transparency is reasonable for a non-destructive operation.

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 with no redundant information. It is front-loaded with the core action and immediately provides essential supplementary instructions.

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 exists, but the description covers the effect (attach to segment) and a critical follow-up step. It omits details like whether multiple SFXs can be added per segment or error handling, but for a focused tool this is adequate.

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

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

Schema coverage is 100% and all parameters have descriptions. The tool description adds extra context for library_track_id by specifying how to obtain it (via browse_audio_library with category='sfx'). This provides meaningful guidance 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 action (attach) and resource (segment, sound effect from audio library). It distinguishes from siblings like remove_segment_sfx and add_music_track by specifying the type of audio item (sfx) and providing a hint to use browse_audio_library.

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

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

The description explains when to use the tool (after obtaining a library_track_id via browse_audio_library) and indicates a necessary follow-up (re-run build_scenes). However, it does not explicitly state when not to use it or provide 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 declare destructiveHint=true, and description adds async behavior and job type detail. No contradiction. Adds value beyond annotations by explaining awaiting pattern.

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, no redundancy. All information is front-loaded and relevant.

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 analysis tool, description provides enough context. Could mention output implications, but no output schema exists. 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 one parameter (style_id) described. Description does not add extra parameter meaning beyond schema, but mentions it indirectly. 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 the tool re-runs style analysis after changing inputs, distinguishing it from related tools like 'create_style' or 'get_style'. The verb 're-run' and resource 'style analysis' are explicit.

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

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

Explicitly says when to use (after changing style inputs) and how to handle the async job (await_jobs). Lacks explicit 'when not to use', but context is sufficient.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly: it discloses billing of video credits, a 400 error when the image is not rendered, rollback behavior on refused generation, and the async contract returning {ai_job_id, segment}. This is far beyond a minimal safe-read/write statement.

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

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

The description is dense but every clause earns its place: core action, sequence semantics, billing, error precondition, rollback, sibling differentiation, and async completion. The structure front-loads the main action and immediately gives the agent the highest-stakes facts.

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?

Even without an output schema, the description states the return shape and follow-up call, making it complete for invocation. It covers prerequisites, failure modes, cost implications, and alternatives, leaving no obvious gap an agent needs before calling the tool.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by tying voice=true to the Talking Head use case and clarifying that the voice flag is 'always explicit, never inferred.' It does not add much for project_id or segment_number, but the schema already documents them well.

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

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

The description states a specific verb and resource: 'Animate one segment in a single call: flip it to a generated video shot... and START the clip render immediately.' It clearly distinguishes itself from change_segment_type, which 'owns the other kind switches,' so an agent can tell this tool from siblings.

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

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

It explicitly frames this call as 'the ONLY way to a generated video' and names the alternative for other segment-type switches: change_segment_type. It also gives the prerequisite (image must already be rendered), the async follow-up (await_jobs), and notes that voice=true is for a Talking Head.

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 critical behavioral context: server-side blocking, repeated calls needed, and return structure {done, jobs}. 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?

Extremely concise: three sentences, each with a clear purpose. Front-loaded with the main blocking behavior, then usage notes. 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?

Despite no output schema, the description mentions the return shape {done, jobs}. Given the tool's simplicity and ample annotations, this is fully complete 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?

Schema coverage is 100%, and the description reinforces key parameter constraints: mutual exclusivity of style_id and project_id, and timeout_seconds <=50. 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 clearly states that the tool blocks until no pending/running jobs or a timeout occurs. It distinguishes itself from polling get_workflow_status, making the purpose unmistakable.

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

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

Explicitly tells when to use (instead of polling), when to call again (if done=false), and provides a timeout constraint (<=50s) to avoid client timeout, giving clear usage guidance.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety behavior is covered. The description adds behavior beyond annotations: returning a {tracks} object and, on zero matches, exposing the actual mood and genre tags the library carries. This gives the agent useful failure-recovery information.

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, all information-dense and purposeful, with the core browse action and result shape front-loaded. The zero-match retry guidance earns its place rather than padding the description.

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

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

For a read-only browse tool with four optional filters, the description covers return shape, filter categories, downstream use, and an edge case (zero matches). It does not mention pagination or result ordering, but those are minor gaps given the simplicity and annotation 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 description coverage is 100%, so the schema already explains all four optional parameters. The description mostly restates the category values and adds downstream usage context, but it does not significantly deepen the meaning of individual 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 states a specific verb and resource: 'Browse the audio library for background music and sound effects,' with the category dimension made explicit. It distinguishes the tool somewhat by describing its result feeding add_music_track / add_segment_sfx, but it does not explicitly differentiate it from sibling list_music_tracks.

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 returns track ids that feed add_music_track / add_segment_sfx, which tells the agent how to use the results downstream. It also gives a retry strategy when zero matches occur, which is practical guidance. It does not explicitly name when not to use it or mention alternatives, so it lacks full exclusion guidance.

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

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

The annotations already indicate destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds useful context about the required pipeline stage and the returned receipt, but it does not explain what a rerun does to existing scenes or what destructive effects to expect.

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

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

The description is compact and information-dense: the action is front-loaded, the pipeline position is stated, and the return shape is summarized without filler. Every clause earns its place.

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

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

For a single-parameter tool, the description covers the action, when to run it, what it returns, and where to get more detail. The destructive safety hint is supplied by annotations, and the output receipt is described inline, so nothing essential is missing.

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

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

There is only one parameter, project_id, and the schema description fully covers it: 'Project ID, as returned by create_project or list_projects'. The description adds no further parameter semantics, so the schema baseline of 3 is appropriate.

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

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

The description clearly states the concrete action: compiling segments, assets, and voiceover into the editor/render timeline (scenes). It also anchors the tool in the pipeline ('after segment assets are complete, before export'), which distinguishes it from later export or inspection siblings like export_video and list_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?

It gives explicit timing guidance: run after segment assets are complete and before export. It does not explicitly name alternatives or when not to use it, but the pipeline positioning plus the pointer to list_scenes for composition detail provides sufficient context.

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

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

Beyond the annotations, the description discloses substantial behavioral nuance: media_source="real" removes start frame and generation, carry_frame is ignored for real targets, SFX/overlays survive type changes, and dry_run previews what would be kept/staled/recreated/deleted. These are the kind of side effects an agent needs to anticipate, and they align with destructiveHint=true.

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 each sentence carries a distinct piece of behavior or constraint, and the core purpose is front-loaded. Slight redundancy with the schema's parameter descriptions and a few informal phrases keep it from a perfect score, but there is no wasted 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 complexity and the absence of an output schema, the description covers the essential operational concerns: valid type transitions, refusal conditions, carry_frame semantics, media_source behavior, survival of SFX/overlays, and dry-run preview. An agent has enough information to call this tool correctly and predict consequences.

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 covers all six parameters, so the baseline is 3. The description earns an extra point by clarifying interactions not fully spelled out in the schema: carry_frame being ignored for real media targets, media_source="real" meaning no start frame and no generation, and the refusal condition for non-real video targets.

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

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

The description states a specific verb and resource: 'Change what a segment's base visual IS', then enumerates the exact type values and their meanings. It also explicitly distinguishes itself from animate_segment by stating that generated video is not set here, so an agent can select it correctly.

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

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

Usage context is explicit: generated video belongs to animate_segment, and a "video" target without media_source="real" is refused. The description also clarifies when carry_frame and dry_run are relevant, giving the agent clear decision rules for 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 mark this as destructiveHint=true, but the description goes much further: the other segment's assets are deleted, kept assets are marked stale, prompts are re-derived, and later segments renumber. This gives an agent concrete, actionable expectations about 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?

Two sentences with no filler. The action and adjacency constraint are front-loaded, and the remaining detail about asset survival, deletion, and renumbering is dense but relevant.

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 destructive consequences, renumbering behavior, and the need to re-fetch segments afterward. It does not state return values or whether the operation is asynchronous, and there is no output schema, but the essential call-time information is present.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches the meaning of the 'keep' parameter beyond the schema by explaining that kept assets remain while the other segment's assets are deleted. It does not add format-level detail for IDs or segment numbers, but the schema already covers those adequately.

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

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

The description opens with a specific verb and resource ('Merge a segment with an adjacent one') and adds a precise constraint ('segment numbers must be neighbors'). This clearly identifies the operation and distinguishes it from segment-related siblings like split_segment.

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

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

The description gives explicit preconditions ('segment numbers must be neighbors') and a clear follow-up instruction ('re-check get_segments before further edits'). It does not explicitly name alternatives for non-neighbor cases or contrast with split_segment, but the usage context is otherwise 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?

All annotations are false, providing no positive safety profile, so the description carries the burden. It does add useful context: the description parameter is a generation-facing spec rendered into shots, the name binds storyboard to script, and created assets behave like scanned assets in the pipeline. However, it doesn't disclose what happens on duplicate names or how creation interacts with existing assets of the same name, and since idempotentHint=false, the agent gets no warning against double-creation.

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 core purpose and key parameter guidance are front-loaded in the first sentence. The second paragraph is somewhat elaborate with examples (host, recurring set) but each clause earns its place by clarifying the failure mode and the naming requirement. No filler, though the examples could be tightened.

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 create tool with no output schema and no enums, the description covers the purpose, the scenario that warrants manual creation, the critical naming constraint, and the next pipeline step. Minor gaps: no indication of what the tool returns after creation and no guidance on handling duplicate names. Overall, an agent can successfully invoke it from this description alone.

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%, giving a baseline of 3. The description goes beyond the schema by explaining the naming semantics in depth (exactly as the script/directions refer to it, so the storyboard binds the two) and by reinforcing that description must be a specific, generation-facing look spec. The asset_type values are restated, which adds little, but the naming rule is genuinely non-obvious guidance the schema lacks.

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?

"Manually add a character/environment/object the scan missed" states a specific verb (manually add), a concrete resource (character/environment/object assets), and the precise scope (things the scan missed). This clearly differentiates it from the automatic scan_script flow and from sibling tools like update_asset, delete_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 gives clear when-to-use context: the scan reads narration and [SCENE] directions, so the common miss is anything neither ever names — a host, a recurring set. It also supplies naming guidance (use the script's exact reference so the storyboard binds) and a follow-up step (generate_asset_reference it). It doesn't explicitly exclude alternatives like 'if the asset already exists, use update_asset instead,' but the scan-miss framing implies the boundary well.

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 write operation (readOnlyHint=false) and no destructiveness (destructiveHint=false). The description adds useful context about channel being a container, but lacks details on side effects, permissions, or return value, which is a gap given no output schema.

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

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

Two sentences, front-loaded with purpose and usage guidance. No extraneous information; every sentence serves a purpose.

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

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

While the description explains the channel concept and usage, it omits critical information for a creation tool: what the response contains (e.g., channel ID or object), any constraints (e.g., name uniqueness), and does not compensate for the lack of output schema.

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

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

Schema coverage is 100% for both parameters (name and description). The description does not add extra meaning beyond the schema's titles and descriptions, 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?

Clearly states 'Create a new channel' as the verb-resource combination, defines channel as 'container for projects and their reusable styles', and distinguishes from sibling tools by saying 'rather than 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?

Explicitly tells when to use the tool ('when the user wants a fresh creative identity') and what not to do ('rather than adding to an existing channel'), providing clear context against alternatives.

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

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

The description discloses key behavioral traits beyond the annotations (which are all false): the description seeds script generation, video_format='portrait' composes everything for 9:16, and the response includes a shareable web_url. This provides useful context without contradicting the annotations.

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

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

Three sentences deliver purpose, parameter advice, and response usage with no filler. Every sentence earns its place and the key information is front-loaded in the first sentence.

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 appropriately highlights the web_url return value. It also covers the behavioral consequences of the description and video_format parameters. It relies on the schema for channel_id sourcing, which is acceptable, but could have mentioned prerequisites in the description itself.

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

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

Although the schema already documents all 4 parameters (100% coverage), the description adds practical semantics: write a meaningful description because it seeds script generation, and the video_format choice is fixed once the storyboard is generated. This goes beyond the schema descriptions.

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

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

The description opens with a clear verb+resource: 'Create a project.' It then elaborates on the implications of the description parameter (seeds script generation) and the video_format parameter, which clearly distinguishes it from siblings like update_project, delete_project, and get_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 implicitly indicates this is the entry point for a new project by explaining that the description seeds script generation and that video_format must be chosen up front. However, it does not explicitly contrast with alternatives like update_project or generate_script, so the guidance remains 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?

With minimal annotations (only readOnlyHint=false, destructiveHint=false), the description carries the full burden and succeeds: it discloses mutual exclusivity of inputs/presets, async analysis behavior for references, instant execution for presets, channel/@handle resolution semantics, and a note about REST-only file uploads. This goes far beyond the annotations and adds critical 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?

The description is well-structured, front-loaded with the core purpose, and every sentence adds information. The two-path breakdown with examples is economical and readable despite the length, with no filler or repetition of schema content.

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

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

For a creation tool with async behavior, no output schema, and two mutually exclusive input modes, the description covers prerequisites, sequencing (await_jobs), alternative REST endpoint, and required IDs from sibling tools. It is fully actionable for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances this by providing a concrete example structure for inputs and presets, explaining that presets require all three axes (art, narrative, director), and noting that channel/@handle resolves to the newest usable upload. These details go beyond the schema's field descriptions.

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

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

The description opens with 'Create a style'—a specific verb and resource—and then details two distinct creation paths (references and presets), clearly distinguishing this from sibling tools like update_style_fields, analyze_style, and get_style. The scope is unambiguous and well-differentiated.

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

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

The description explicitly states when to use each path ('References (best)' vs 'Presets (instant)'), mentions the need to call await_jobs before using the style, and explains that file references require the multipart REST endpoint, effectively guiding the agent away from this tool for those cases. It also references list_style_presets as a prerequisite source.

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; description adds example of typical deletion scenario. Consistent with annotations, no contradiction, but does not elaborate on 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?

Single sentence, no filler. Every word is necessary for the description of a one-parameter destructive tool.

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 required parameter, destructive hint, and no output schema, the description is sufficient. Example and schema provide complete context.

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

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

Schema already fully describes the single parameter (asset_id) with origin hint ('from list_assets'). Description adds no additional parameter 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?

Clear verb+resource: 'Delete a project asset'. Includes example usage ('one the scan over-extracted') which distinguishes from sibling tools like create_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?

Provides a specific use case (over-extracted assets) but lacks explicit when-not or alternative suggestions. The example gives context for appropriate 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 already mark destructiveHint: true. The description adds specific details on what gets deleted (script versions, assets, etc.) and the irreversible nature, providing context beyond annotations.

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

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

Two concise sentences front-load the core action and immediately follow with key context. 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 delete tool with one param and no output schema, the description fully covers what the tool does, its effects, and usage warning.

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 value by noting the project_id comes from list_projects, aiding in parameter selection beyond the schema's basic 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 (permanently delete) and the resource (project) with a specific list of contents affected. It distinguishes from siblings like create_project and 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 warns about irreversibility and advises confirming with the user, which guides appropriate usage. However, it does not explicitly mention when not to use it or alternatives.

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

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

Annotations already mark destructiveHint=true. The description adds context: warns about deleting styles used as defaults and suggests rebinding. This goes beyond the annotation flag, though it doesn't detail reversibility or 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 two sentences with no fluff. The main purpose is front-loaded, and the caution is concise. Every word earns its place.

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

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

For a simple deletion tool with one required parameter and clear annotations, the description covers purpose, usage, and a crucial pitfall (default styles). It is complete given 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?

The single parameter style_id has full description in the schema ('ID of the style to delete, from list_styles'). The tool description does not add additional semantics beyond what the schema provides. Baseline score 3 as 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 'Delete a style' with an example use case (failed analysis experiment). It distinguishes from sibling tools like set_project_style, create_style, and update_style_fields by explicitly mentioning when not to use it and what to do instead.

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 when to use (delete a style, e.g. failed experiment) and when not to (if projects still use it as default), providing an alternative: rebind with set_project_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?

With annotations all false (no positive hints), the description carries full responsibility and does so thoroughly. It discloses synchronous execution, return contents ('applied mutations + updated scene'), locked scene durations, and that segment_number always resolves to the current scene. This goes well beyond the bare schema.

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

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

Four dense sentences, each earning its place: purpose/capabilities, synchronous return, addressing/scene-id guidance, and the duration constraint with a sibling-tool pointer. No redundancy, 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?

For a 5-parameter tool with no output schema, the description is remarkably complete. It covers the return value (mutations + updated scene), critical constraints (duration lock, fresh scene_id), and the sibling alternative. The only minor gap is unspecified precedence if both scene_id and segment_number are passed, but this is negligible given the explicit preference.

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 crucial semantic guidance: it explains why project_id + segment_number is preferred (resolves to current scene), warns that scene_ids become stale after edits, and clarifies that conversation_history can continue a prior chat. This is genuinely useful parameter context beyond the schema.

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

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

The description opens with 'Edit ONE scene with a natural-language note' — a specific verb (edit) and resource (one scene) — and enumerates concrete actions (move/restyle/add/remove layers, retime). It also distinguishes itself from the sibling tool 'project_director_note' by explicitly stating that whole-video notes should go there.

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

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

Provides explicit when-to-use guidance: 'For notes spanning the whole video use project_director_note instead.' Also gives scene-addressing best practices (prefer project_id + segment_number, avoid stale scene_ids) and behavioral constraints (don't extend/shorten scenes except the final one). This clearly orients the agent on how and when to invoke the tool.

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

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

Annotations indicate readOnlyHint=false (not read-only) and destructiveHint=false. The description adds that the tool is async ('Async — poll...') and queues a render job, providing behavioral context beyond annotations. It does not detail side effects or failure scenarios.

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 very concise: two sentences immediately conveying the core action and async workflow. Every sentence adds value with zero 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 single parameter and no output schema, the description adequately covers the tool's role and the async flow. It could mention the need for a complete timeline, but overall it is sufficient 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 coverage is 100% and the schema description for project_id is clear: 'Project ID, as returned by create_project or list_projects.' The tool description does not add additional 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 'Render the final MP4 (Remotion)' and explains the process: 'Fetches the current timeline and queues the render.' It distinguishes from siblings like get_video_url and get_workflow_status by describing the async workflow and next steps.

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-call steps: 'poll get_workflow_status for the video_export job, then call get_video_url.' This guides the agent on usage. However, it does not specify when not to use this tool or prerequisites like a valid timeline.

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 show readOnlyHint=false and destructiveHint=false. Description adds that the tool is async and writes the image onto the asset row, disclosing side effects clearly.

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. The second sentence is a bit long but packs necessary 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?

Despite no output schema, the description explains the full lifecycle: async job, how to check completion (await_jobs), and how to view the resulting image (list_assets, view_image). Complete for a job-triggering 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 the schema already documents all parameters. The description adds workflow context but no additional parameter-level details 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 tool renders an asset's reference image in the channel's art style, serving as a visual anchor. It distinguishes itself from generate_voiceover by noting the dependency order.

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 this before generate_voiceover, and provides a clear workflow: fire jobs for all assets, then await_jobs, then list_assets and view_image to check result.

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

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

The description discloses async behavior and the need to poll 'get_workflow_status', adding behavioral context beyond the all-false annotations. It does not cover potential side effects, but the 'generate' verb implies non-destructive creation.

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 and front-loaded sentences: the first states the purpose, the second describes the async pattern. No redundant information.

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

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

The description covers core behavior and async workflow. It could mention prerequisites like existing project and channel narrative style, but the schema references provide sufficient context.

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

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

Schema coverage is 100% and each parameter is well-described in the schema. The description adds no additional parameter meaning, so baseline of 3 is appropriate.

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

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

The description clearly states it generates a script from the project's description/concept and the channel's narrative style, distinguishing it from related siblings like 'revise_script' or 'scan_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 implies usage for initial script generation but does not explicitly provide when to use this tool versus alternatives such as 'revise_script' for modifications.

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

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

The description adds substantial behavioral context beyond the annotations: this is the most expensive pipeline call, prior permission does not cover it, re-runs skip completed and currently-generating assets, and execution is async with one job per asset requiring await_jobs. This aligns with idempotentHint=true and gives the agent critical operational guidance.

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

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

The description is dense but every sentence earns its place: purpose, cost warning, staged workflow, subset guidance, idempotency, and async behavior. The most important operational warning is front-loaded immediately after the purpose statement, and there is no filler.

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

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

Given the high complexity and no output schema, the description covers the full decision workflow: dry-run before spending, staged scope selection, subset rendering, re-run safety, and async completion via await_jobs. It also references related tools (get_credit_balance, animate_segment, get_segments) that the agent will need to execute correctly. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value by showing how parameters work together: using asset_scope="no_clips" as a cheap first pass, and passing segment_numbers like 1-18 to render only the opening minute before committing to the full video. This converts bare parameter options into a coherent invocation strategy.

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

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

The description states a specific verb and resource: rendering every actionable segment asset (images, video clips, overlays) across the project in dependency order. It clearly differentiates this bulk generation tool from siblings like animate_segment and regenerate_segment_asset by emphasizing project-wide scope and dependency ordering.

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

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

The description gives explicit when-to-use instructions: always run with dry_run=true first, show the credit estimate alongside get_credit_balance, and require fresh user approval before the real run. It also prescribes a staged workflow using asset_scope="no_clips" then animate_segment, and explains when to use segment_numbers for subset rendering.

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 carry only the mutation/destructive profile (destructiveHint=true, readOnlyHint=false); the description adds genuinely new behavioral facts the schema cannot express: async execution, exact return shape ({job_id}), relative latency ('longest LLM step'), and a processing boundary (video deliberately deferred to animate_segment). The @real-media tag constraint also discloses a failure condition in advance. No statement contradicts 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?

Four sentences, each carrying distinct information in a logical order: purpose → prerequisite → scope boundary → async/latency. Critical facts are front-loaded and there is zero redundancy or filler; the density is justified by the tool's async, multi-phase complexity.

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

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

For an async tool with no output schema, the description covers what it does, what it requires, what it deliberately excludes, and what it returns — enough for correct invocation. The only omission is an explicit pointer to poll via await_jobs, though that is inferable from the {job_id} return and the sibling list.

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 each parameter already carries a rich description referencing sibling tools (list_models, get_section_template). The tool description adds only indirect context — the voiceover prerequisite implies project_id must reference a voiced project, and 'director and art styles' explains what drives model/settings choice — but no parameter-specific 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?

States a specific verb ('Plan') and resource ('the full visual storyboard') with enumerated deliverables — segments, shot pacing, image/video prompts, overlays, continuation chains. The visual-planning focus differentiates it from siblings like generate_script, generate_voiceover, and generate_segments, and the 'full' scope distinguishes it from per-segment 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?

Gives an explicit prerequisite ('Requires voiceover to exist (timing comes from it)') that tells an agent when it is valid to call, and routes the next pipeline step to animate_segment ('generated video is added... with animate_segment'). Lacks an explicit when-not-to-use statement naming alternative planners such as generate_segments, so it falls short of a 5.

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

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

Annotations provide no safety hints (all false), so description carries full burden. It discloses that overwriting re-anchors future renders, that an existing template causes refusal unless replace=True, and that the operation is async.

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?

Dense but every sentence adds unique operational info: purpose, rationale, prerequisites, edge case, and async guidance. Front-loaded with the core purpose, avoiding 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?

Despite no output schema, the description fully covers purpose, workflow position, edge cases, and async behavior. It directs to await_jobs and get_style to verify completion, making it operationally 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 covers 100% of parameters with descriptions, so baseline is 3. Description adds workflow context (run once per type, replace semantics, async follow-up) that goes beyond the schema, justifying a 4.

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

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

States 'Render one of a style's two template images' with a specific verb and resource. Explicitly distinguishes from generate_asset_reference and refers to get_style for checking existing templates.

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

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

Provides explicit when-to-use and when-not-to-use guidance: run once per template_type, skip types the style already has, finish both before generate_asset_reference. Also explains the hard stop and replace=True exception.

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 re-call safety, skipping of already-generated/currently-generating blocks, no double-billing, and async return of one job per block. This adds meaningful context beyond the annotations, especially since idempotentHint is false but the gap-fill mode is idempotent.

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 dense paragraph with every sentence earning its place. Front-loaded with the main action, followed by mode behavior, safety, prerequisites, and async note. No 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?

Covers all critical aspects: operation, two invocation modes, safety semantics, prerequisites, optional parameter scope, and async return behavior. With no output schema, the 'returns one job per block' statement suffices. References companion tools for deeper 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?

Schema coverage is 100%, so baseline is 3. The description adds semantic value by explaining voice_block_ids behavior (gap-fill vs explicit regeneration), the scope of settings/editable_sections (applied to every selected block), and referencing where to find valid keys.

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 starts with a specific verb+resource ('Generate TTS audio for the project's voice blocks') and immediately distinguishes two usage modes: gap-filling without voice_block_ids and explicit regeneration with them. This clearly differentiates it from siblings like list_voice_blocks and update_voice_block.

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

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

Provides explicit when-to-use guidance: omit voice_block_ids to fill gaps safely, pass them to REgenerate. States prerequisite (voices bound via set_narrator_voice/set_character_voice) and points to get_section_template and list_models for optional parameter details.

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, idempotentHint=true, destructiveHint=false, so the description does not contradict them. It adds useful context about what data is returned (balance and plan info) and billing behavior, which goes beyond annotations.

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

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

Two short sentences; first states purpose, second gives usage guidance. No wasted words. Front-loaded and 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 tool with no parameters and no output schema, the description fully covers what it does and when to use it. The billing nuance adds 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 input schema has 0 parameters with 100% schema description coverage. Baseline is 4. The description does not need to add parameter info, and it doesn't.

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 provides 'current credit balance + plan info', which is a specific verb+resource combination. No sibling tool overlaps with this purpose, so it is 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?

Explicitly advises to check before expensive steps, provides a concrete example (full segment render costing hundreds of credits), and mentions alternative (generate_segments dry_run for estimate). Also clarifies that BYOK jobs bill 0. This is excellent guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds context that it provides comprehensive state, web URLs for step outputs, and next_action guidance, which is behaviorally rich.

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 paragraphs, front-loaded with purpose and usage. The second paragraph adds important web_url guidance, though it slightly extends beyond core purpose.

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

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

Completes the picture for a complex pipeline tool without output schema: explains return structure, step list, next_action role, and web URL usage. No gaps for agent to infer.

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

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

Schema coverage is 100% with one parameter (project_id) that has a clear description. The description adds minor clarification about project_id source but does not significantly extend 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 clearly states it returns every pipeline step's state, running jobs, and next_action, using specific step names. It distinguishes itself as a resume/orientation tool from sibling tools that perform individual pipeline actions.

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 call: when picking up an existing project, after await_jobs, or when unsure of video status. Includes directive 'never guess pipeline position'.

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, idempotentHint, and destructiveHint, indicating a safe read operation. The description adds value by detailing the response content (settings, voice config, etc.), which goes beyond the annotations and informs the agent of what to expect.

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

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

The description is a single sentence that conveys the essential information without any fluff. Every word is meaningful, and the structure is front-loaded with the action and resource.

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 is complete. It explains what data is returned, compensating for the lack of an output schema. The context signals and sibling tools further clarify its role.

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

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

The input schema has 100% coverage for the single parameter project_id, with a clear description in the schema. The tool description does not add additional semantics beyond what is already in the schema, 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 'Fetch a project row' and lists specific fields returned (settings, voice config, default style, export URL), making the purpose explicit and distinct from sibling tools like create_project, 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?

The description implies use for retrieving a single project by ID, which is clear. However, it does not explicitly state when not to use it (e.g., use list_projects for browsing or update_project for modifications), so it lacks explicit exclusion guidance.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by specifying the exact return content (full text + version list), which goes beyond the 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?

Two concise sentences, front-loaded with the main purpose. No extraneous 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 a single required parameter, no output schema, and comprehensive annotations, the description provides sufficient context about the tool's role in the workflow and expected 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%, so the schema already documents the single parameter (project_id) adequately. The description does not add new parameter semantics 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 tool reads the active script's full text and version list. The verb 'Read' and resource 'script' are explicit, and it distinguishes itself from sibling tools like scan_script or 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 explicitly instructs to use this tool before scan_script and within a review-edit-resave workflow. It provides clear guidance on when and how to use this tool versus 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. Description adds key behavioral detail: 'Sections marked locked cannot be overridden', which is 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, no fluff. Purpose stated upfront, followed by essential behavioral constraint. 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?

Simple tool with one parameter; description sufficiently explains input and expected output (list of sections with locked flag). No output schema 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 covers the single parameter 'job' with 100% description coverage (lists examples). Description reiterates examples and adds context linking to editable_sections, but adds little new 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?

Description explicitly states 'Inspect the prompt sections a generation job exposes for per-call override via editable_sections', clearly defining verb, resource, and purpose. Includes example job names, distinguishing it from siblings.

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

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

Implicitly clear when to use: to inspect editable sections before overriding. No explicit exclusions or alternatives, but context and sibling list make purpose distinct.

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, destructiveHint. Description adds return details (status, config, public URLs) which is useful but not extensive. 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?

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

No output schema, but description adequately explains return content (status, config, public URLs) and hints at next step (view_image). Complete for a listing tool with two required params and good annotations.

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 clear descriptions for both parameters. Description does not add additional parameter-level information, 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 specifies verb 'list', resource 'one segment's assets', and includes details on what is returned (status, config, public URLs). It also distinguishes from sibling 'view_image' by noting that to view an image, use 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?

Explicitly states the tool lists assets for a segment and provides guidance to use view_image for actually viewing images. Lacks explicit when-not-to-use but the context is clear.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, and the description reinforces a pure listing behavior with no side effects. It adds substantial value beyond annotations by documenting the return shape ({total, offset, returned, segments}), the pagination behavior, and the semantics of continues_from_segment including the visual carry-over of continuation shots. 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 short, logically organized paragraphs: scope/handle, response shape/pagination, then continuation semantics. The front-loaded first sentence tells the agent exactly what the tool returns, and every later paragraph earns its place by explaining the response and the key returned field. Despite the length, it reads efficiently and avoids 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?

Because there is no output schema, the description carries the burden of explaining the return value, and it does so clearly: the segments list, pagination envelope, and meaning of continues_from_segment. Required parameter project_id, pagination options, and the next-step tools (set_segment_continuation, update/split/combine) are all addressed. This is complete enough for an agent to select and invoke the tool correctly without further inference.

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

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

The input schema already provides 100% parameter coverage, with detailed descriptions for project_id, limit, and offset, so the description carries little burden. It does reinforce the offset/limit pagination pattern, but this largely mirrors the schema's own wording ('page with offset/limit instead of pulling everything at once'). It adds no new parameter-specific 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?

Opens with a specific verb and resource: 'List the storyboard's segments' and enumerates the returned fields (narration span, type, duration, creative direction). It also clarifies the segment_number handle, distinguishing this as the canonical list/metadata tool among many segment-related siblings. The title 'List segments' reinforces the clear scope.

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

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

The description tells the agent this is where to obtain the 1-based segment_number used by every segment mutation tool, implying a natural 'list first, then update/split/combine' workflow. It also gives explicit pagination guidance via offset/limit for large projects. It doesn't name alternative tools directly or state when not to use it, but the context is clear.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description reveals important state semantics: null vs URL template meaning, the fact that inputs_stale indicates analyzed fields are outdated, and the downstream consequences of those states. This is meaningful behavioral context not present in the annotations.

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

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

The description is dense and every clause earns its place, covering the return shape, null/URL handling, and stale-input behavior. It is slightly long but justified by the semantic complexity of the tool's return state.

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

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

With no output schema, the description carries the burden of explaining return values and state interpretation. It covers the main fields, the templates object, null semantics, and inputs_stale behavior, giving an agent everything needed to correctly act on the response.

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

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

There is only one parameter, style_id, and the schema already documents it fully as 'Style ID, as returned by create_style or list_styles.' The description adds no new parameter detail, but with 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource ('Fetch one style row') and enumerates exactly what that row contains: inputs, analyzed fields, and templates. It is clearly distinguishable from sibling tools like list_styles, analyze_style, update_style_fields, and generate_style_template.

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 conditional routing guidance: null template values should lead to generate_style_template, URL values to view_image, stale inputs to analyze_style, and review/fine-tuning to update_style_fields. This explicitly tells an agent when to use this tool versus related alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, indicating a safe read. The description adds contextual details: it returns a download URL for the 'most recent completed export,' which is helpful 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?

The description is a single concise sentence with no wasted words. It is front-loaded and directly tells the agent what the tool does.

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 parameter and clear annotations, the description is mostly complete. It could mention that the export must have been completed, but this is implied. No output schema needed for this context.

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

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

Schema coverage is 100% with a single parameter (project_id) described as 'Project ID, as returned by create_project or list_projects.' The description does not add any additional meaning beyond what the schema already 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 title 'Get video download URL' and description 'Download URL for the most recent completed export' clearly state the verb (get/download) and resource (video URL). It distinguishes from siblings like export_video which creates exports, and other get_ tools which retrieve different entities.

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 after an export is completed but does not explicitly state when to use this tool versus alternatives, nor does it mention prerequisites (e.g., an export must exist). No guidance on when not to use it.

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

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

Annotations already declare readOnlyHint and destructiveHint. The description adds crucial behavioral context: finished jobs drop out after ~30s, a short list does not mean work lost, and how to correctly assess render batches. 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?

Four sentences, well-structured, with clear language and a notable warning in bold. No wasted 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 (transient jobs, multiple scope options), the description covers usage, interpretation of results, and links to sibling tools. No output schema exists, but the description hints at return structure (jobs, segment_assets, error messages) adequately.

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 both parameters. The description adds minimal extra value (e.g., 'for style analysis' for style_id) but largely repeats what the schema already states. 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 returns active and recently-finished AI jobs, scoped by project_id or style_id, plus per-segment-asset render statuses. It distinguishes itself from siblings like await_jobs and get_pipeline_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?

Explicitly advises polling between steps, recommends preferring await_jobs over tight polling, and warns against counting jobs to judge render batches. Provides clear when-to-use and alternative guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds useful behavioral context: the output structure (description surfaced top-level, file_path as public URL, voice_id for characters) and the asset_type filter behavior. It does not contradict annotations.

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

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

The description is concise with two sentences plus a clause. It front-loads the purpose, then provides workflow context, then filter details. Every sentence is necessary and informative, 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 simple tool (2 params, no output schema) and rich annotations, the description fully covers what the tool does, what the output contains, and its place in the workflow. It explains the asset types, their attributes, and recommended next steps, making it self-contained.

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 adequate descriptions for both parameters. The description adds value by explaining the asset_type filter values explicitly ('character', 'environment', 'object') and indicating that empty lists all types. It also clarifies the project_id context.

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', the resource 'assets', and the scope 'project's assets extracted by scan_script'. It distinguishes from sibling tools like create_asset, delete_asset, update_asset by specifying the source and context.

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 on when to use this tool: 'Review these after scan_script'. It also gives next steps: 'fix descriptions, then generate_asset_reference for each one'. It doesn't explicitly state when not to use or list alternatives, but the context is clear.

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

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

Annotations already indicate a safe, read-only operation. The description adds value by explaining that channels own reusable styles, which is behavioral context beyond the annotations. No contradictions or missing disclosures for this simple list.

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

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

The description is two sentences long, front-loaded with the action, and every sentence provides essential information. No extraneous content.

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

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

For a simple read-only list tool with no parameters and comprehensive annotations, the description sufficiently covers what the tool does and the context of channels. No output schema exists, but the description doesn't need to detail returns for such a standard operation.

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

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

There are zero parameters, so schema coverage is trivially 100%. The description does not need to add parameter details, and the baseline for zero parameters is 4. No additional parameter information is required.

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 'your channels', which is specific and distinct from sibling list tools like list_projects or list_assets. The additional sentence explains the role of channels, reinforcing the tool's purpose.

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

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

The description provides no guidance on when to use this tool versus alternatives such as list_projects or list_styles. It simply states what it does without context for selection or exclusion.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds genuine behavioral context beyond annotations: server-side model selection fallback, the meaning of settings_schema, and the provider matching requirement for voice_block models. 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 dense sentences, front-loaded with the main purpose, followed by two high-value clarifications about fallback behavior and voice model constraints. Every sentence earns its place and there is no redundant or filler content.

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

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

For a one-parameter read-only list tool with no output schema, the description covers return fields, fallback behavior, and a critical voice-model constraint. Minor gaps such as pagination or ordering are unlikely to matter here, and the description carries the burden well in the absence of an 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?

The input schema already fully documents the single job parameter with examples, and schema coverage is 100%. The description references job/scope but adds no new syntax or constraints for the parameter itself; the extra detail about settings_schema and provider applies to returned fields, not parameter usage.

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 opening sentence names a precise verb and resource: list the allowed models for a generation job, and specifies the returned fields (display names, credit estimates, settings_schema). This clearly distinguishes it from sibling list tools by tying it to generation jobs and model settings.

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 concrete usage context: what happens when model is omitted, the fallback to the account's saved expert-drawer choice, and the voice model provider constraint relevant to generate_voiceover. It does not explicitly name alternatives or state when not to use this tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds useful context about the returned properties (volume, loop, timing), going 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?

Single sentence, front-loaded with verb and resource, 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 simple tool with one param and rich annotations, description explains what is returned (volume, loop, timing). However, could be more explicit about listing all tracks and output structure.

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

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

Schema coverage is 100% for the single parameter, with a good description in the schema. The tool description does not add any additional param information 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?

Description uses specific verb 'list' and resource 'background music tracks' with properties (volume, loop, timing). Clearly distinguishes from sibling tools like add_music_track 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?

No explicit when-to-use or alternatives provided. The purpose is implied from sibling tool names, but lacks guidance on prerequisites or 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 the tool as read-only, idempotent, and non-destructive. The description does not add any behavioral context (e.g., pagination, error handling, rate limits, or what happens if the channel is not found). It adds no value 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 a single sentence with no unnecessary words, achieving maximum conciseness. It is well-front-loaded with the core purpose.

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

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

Despite the simple structure (1 required param, no output schema), the description fails to explain what is returned (e.g., list of project IDs or full objects). Without output schema, description should specify return format. Also lacks details like ordering, filtering, or limits.

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% (channel_id has a description). The tool description does not mention parameters, so it adds no additional meaning beyond the schema. Baseline of 3 is appropriate.

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

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

The description 'List projects in a channel' clearly specifies the verb (list), resource (projects), and scope (in a channel), effectively distinguishing it from sibling tools like get_project (single project) or create_project (create).

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 like get_project or list_assets. It does not mention prerequisites, ordering, filtering, or pagination. The schema parameter description hints at obtaining the channel_id from other tools, but the description itself offers no usage context.

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

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

The description adds meaningful behavioral details beyond the annotations: the masking behavior ('only the last 4 characters') and the interpretation of an empty result. These are not available in the annotations or schema, making the description genuinely informative.

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 compact sentences deliver the key facts with no filler. The main behavior (list masked provider keys) is front-loaded, and the return semantics are stated immediately afterward.

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

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

For a zero-parameter, read-only, idempotent list operation, the description fully covers what an agent needs: what is returned, how it is masked, and how to interpret an empty list. The annotations already cover safety, so nothing critical is missing.

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

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

The tool has zero parameters and 100% schema coverage, so parameter documentation is structurally complete. The description adds no parameter details, but none are needed; per the baseline for zero-parameter tools, this is appropriate.

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

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

The description states a specific verb ('List') and resource ('registered BYOK providers') and adds a distinguishing detail: keys are masked to the last 4 characters. This clearly sets it apart from sibling list_* tools without needing to inspect schemas.

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

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

The description provides clear context by explaining the return shape and the meaning of an empty list (no keys registered, so jobs bill platform credits). It does not explicitly name alternative tools or exclusion conditions, but the resource is distinct enough that usage is well implied.

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

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

Beyond the readOnly/idempotent annotations, the description discloses timeline ordering, the difference between summary and full composition output, the bulk/volume warning, and the exact response envelope {total, offset, returned, scenes}. This gives the agent a realistic expectation of cost and output without contradicting the annotations.

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

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

The description is compact and front-loaded: it states the core behavior first, then the mode trade-off, then the return shape. Every clause contributes useful information with no repetition 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?

There is no output schema, but the description supplies the response wrapper shape and enough detail about both output modes to interpret results. Combined with annotations covering side-effect safety, nothing an agent needs to invoke or understand the tool is missing.

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

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

The schema already documents all four parameters with 100% coverage, so the baseline is 3. The description adds value by explaining when summary fields suffice, warning that include_composition is bulky, and explicitly tying offset/limit to pagination on long projects.

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

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

States a specific verb ('List'), resource ('the project's scenes'), and ordering ('timeline order'), clearly distinguishing it from sibling listing tools for other resource types such as list_assets, list_projects, and list_styles. There is no ambiguity about what the tool returns.

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 usage context: default light summaries are enough to address a scene by id or number, while include_composition=True returns bulky JSON and should be paginated for long projects. It does not explicitly contrast against a sibling alternative, but the tool's role and the trade-off between modes are clearly laid 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?

The description goes beyond annotations by revealing that art presets include preview image URLs viewable with view_image, and that creation via create_style is instant with no analysis job. This adds significant 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?

The description is well-structured and front-loaded, but slightly verbose with some redundant phrases. Still, every sentence adds value and the structure aids quick parsing.

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 output schema, the description fully compensates by explaining the output format, usage flow, and relationship to other tools. No gaps remain for an agent to understand the tool's role.

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

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

There are no parameters, but the description enriches understanding by detailing what the output contains (labels, descriptions, preview URLs) and how to use them, which is the essence of parameter semantics for this tool.

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

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

The description clearly states the tool lists curated presets for a no-AI style creation path, grouped by axis (art_style, narrative_style, director_style). It distinguishes this from other style tools like list_styles and the analysis path, providing a specific verb and resource.

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 guidelines are given: show the user labels + descriptions, let them pick per axis, do not choose silently. It also directs the agent to create_style for instant creation, effectively guiding tool selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds context about what the styles contain, but does not mention pagination, ordering, or return format. Extra detail would improve transparency.

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 redundancy, front-loaded with the action. Every word adds value. Excellent 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?

For a simple list tool with one parameter and no output schema, the description covers purpose and what the items represent. A minor gap is the lack of explicit mention that the output is a list of style objects, but it is implied by 'List the channel's style rows.'

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 (channel_id) is fully described in the input schema with a clear description. With 100% schema coverage, the description adds no additional parameter semantics beyond the schema, hitting the baseline.

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

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

The description clearly states the tool lists 'style rows (variable groups)' and mentions specific fields (art_style, narrative_style, etc.), making the purpose specific. However, it does not explicitly differentiate from sibling tools like get_style or create_style, which would push it to a 5.

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

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

The description explains that styles 'drive every generation step,' implying when to use this tool (to see styles affecting generation), but it gives no guidance on when not to use it or how it compares to alternatives like get_style or analyze_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 goes well beyond the annotations by explaining the semantics of scene_direction (never spoken, null when absent) and by disclosing that subtitle timings are stripped by default unless include_subtitle_data=True. These are non-obvious behaviors an agent needs to interpret results correctly.

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

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

The description is compact and every sentence earns its place: purpose, field clarification, and default behavior. It is front-loaded with the core action and keeps supporting details brief.

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

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

For a simple read-only list tool, the description covers what is returned (audio status, assigned voices), clarifies a key field's semantics, and explains the optional parameter's effect. With annotations already covering safety and idempotence, nothing essential is missing.

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

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

Schema description coverage is 100%, and both parameters are already well documented. The description reinforces the include_subtitle_data behavior but adds no meaningfully new parameter information beyond the schema.

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

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

The description states a specific verb and resource: 'List the project's voice blocks', and clarifies exactly what a voice block is ('per-speaker narration chunks'). It also differentiates the resource from sibling tools by focusing on voice blocks rather than scenes, segments, or 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: an agent should use this when it needs voice blocks with audio status and assigned voices. However, it does not explicitly discuss alternatives such as update_voice_block or rescan_voice_blocks, nor does it state when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavior beyond annotations: it reveals the response shape ({groups, voices}) and warns about the large ElevenLabs catalogue, guiding the agent to filter.

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

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

Three dense sentences with no filler: purpose, provider guidance, and response/filtering note are each front-loaded and necessary. The structure makes the key operational detail (large catalogue, use groups) easy to find.

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 low-complexity read-only tool with richly annotated schema and no output schema, the description supplies the essential missing pieces: return shape, provider-project matching, and group filtering. Nothing critical is left unexplained.

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

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

Schema description coverage is 100%, so the schema already documents both 'group' and 'provider' well. The description reinforces the provider choices and the group-filtering strategy but does not add substantial new 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 starts with a specific verb and resource: 'List available TTS voices' and names the returned fields (id, label, preview audio URL). It also distinguishes the two provider engines, making the tool's scope clear relative to sibling tools like list_voice_blocks.

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

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

It gives clear practical context: match the project's voice_tts_provider (pointing to get_project) and filter by group for ElevenLabs to avoid reading 150+ voices. It does not explicitly name exclusions or alternatives, but the guidance is sufficient for correct 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?

Disclosure goes well beyond annotations: synchronous, per-scene processing, returns per-scene results, and necessity to re-run export_video. No annotation contradiction.

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

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

Two sentences, front-loaded with purpose, no filler. 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?

Describes behavior, post-conditions, and return value despite no output schema. With full schema coverage, handles completeness well.

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 100%, description adds natural language examples to 'message' but no new meaning beyond schema. 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?

Starts with 'Apply a project-WIDE director note' with concrete examples, clearly distinguishing from sibling director_note (likely per-scene). Specific verb+resource+scope.

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

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

Describes when to use (project-wide note) and post-condition (re-run export_video). Lacks explicit exclusions or alternative tools, but context with sibling provides implicit 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 are non-committal (no readOnly/hints), but the description adds key behavioral details: async execution, returns {job_id}, and that it is the API equivalent of the editor's expert drawer. This goes beyond annotations.

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

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

The description is concise (4 sentences) with no wasted words. It front-loads the main purpose, then clarifies key parameters and async behavior, making it easy to parse quickly.

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

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

Given no output schema, the description adequately explains the return value ({job_id}). It also references related tools for parameter details, making it self-contained for an agent. No gaps are apparent.

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, but the description adds context beyond the schema, such as clarifying that asset_type 'image' for a video segment targets the start frame, and listing the purpose of editable_sections and settings.

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, explicitly mentioning asset_type and async behavior. It distinguishes itself from siblings by focusing on regenerating individual 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 explains when to use the tool (re-run just this asset with different model, overrides, settings) and references related tools like get_section_template and list_models. However, it does not explicitly state when not to use it 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 set destructiveHint=true, so description confirms removal but adds no new behavioral details (e.g., irreversibility, permissions). Does not contradict 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, no unnecessary words, directly conveys the tool's function.

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 one parameter, the description is sufficient. No output schema needed. Could mention if operation is reversible, but still 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 has 100% coverage with description for track_id including source hint 'from list_music_tracks'. Description adds context beyond schema, improving parameter clarity.

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 clear verb 'remove' and resource 'music track' with scope 'project'. Distinguishes well from siblings 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?

No explicit guidance on when to use this tool vs alternatives (e.g., when to remove vs update). It mainly states the action without context on prerequisites or side effects.

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 (removal) and adds important behavioral detail: the conditional requirement for sfx_name based on the number of attached SFX. It does not contradict annotations. The description goes beyond what annotations provide by specifying the source of the asset name.

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

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

Two sentences, each earning their place. The first sentence states the core action. The second provides critical 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?

For a simple deletion tool with 3 well-documented parameters and no output schema, the description provides sufficient context without needing to explain return values. It could mention failure handling, but it's not essential for a basic removal operation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying the conditional nature of sfx_name in a more natural language, reducing ambiguity for the agent.

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

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

The description clearly states 'Remove a sound effect from a segment', specifying the verb (remove), resource (sound effect), and scope (segment). It distinguishes itself from siblings like 'add_segment_sfx' 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?

The description provides explicit guidance on when to include the sfx_name parameter: 'With one SFX attached, no name needed; with several, pass sfx_name.' It also references 'get_segment_assets' for retrieving the correct name, helping the agent determine the right usage context.

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

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

The description repeatedly claims this is 'non-destructive' and that it works 'WITHOUT touching assets or their reference images,' but the annotations set destructiveHint=true. This is a direct contradiction about core side effects, making the description actively misleading rather than transparent.

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

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

The description front-loads the core behavior and exclusion, then adds only high-value context: re-scan behavior, follow-up guidance, execution mode, cost, and return value. Every sentence earns its place; there is no filler.

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

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

For a single-parameter tool with no output schema, the description is otherwise quite complete: it states the return shape, the behavior on unchanged vs. edited blocks, and the recommended follow-up. However, the destructiveHint contradiction creates a critical gap in safety context, so the description cannot be considered fully trustworthy or 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 only parameter, project_id, is fully described in the schema, including its source ('as returned by create_project or list_projects'). Schema coverage is 100%, so the description need not add param-level 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 names a specific verb ('Re-extract') and resource ('voice blocks from the active script'), and immediately distinguishes itself from scan_script. Even without reading the schema, an agent understands exactly what this tool does and how it differs from its closest sibling.

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 it ('after a script edit'), names the alternative it replaces (scan_script), and prescribes the follow-up tool (generate_voiceover) for edited blocks. This is model usage guidance with clear conditions and next steps.

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 goes well beyond the annotations by disclosing that the tool is synchronous, returns {revised_text}, does NOT save changes, preserves [SCENE: ...] directions, and requires explicit follow-up with save_script. This gives the agent a full picture of side effects without contradicting the annotations.

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

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

Three dense, front-loaded sentences cover purpose, key constraints, preservation behavior, synchronization, return value, and the required follow-up. Every sentence earns its place, with no redundant elaboration or restating of the title.

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 only 3 parameters, no output schema, and no nested objects, the description fully equips an agent to invoke the tool correctly. It explains return shape, non-persistence, selected_text constraints, scene-direction handling, and the save_script workflow, so no critical operational detail is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context by explaining selected_text's verbatim requirement and that omitting it revises the whole script, plus clarifying the output shape. This goes beyond the schema's terse parameter 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 a specific action ('AI-rewrite a passage') on a specific resource ('the active script') in a defined style ('the project's narrative voice'). It also distinguishes itself from nearby tools like generate_script and save_script by noting it's the same as the in-editor revise UI and explicitly not saved.

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 on how to use the tool: selected_text must match verbatim, omit it for the whole script, and follow up with save_script. It does not explicitly name alternative tools or state when not to use it, but the workflow is unambiguous enough for an agent to choose correctly.

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

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

With only false boolean annotations, the description carries the behavioral burden and does substantial work: it discloses that the last 5 renders are archived, the previous render is archived in place so the rollback itself is reversible, and rolling back an image marks the rendered clip out of date. This goes well beyond the schema and annotations, though it does not describe failure modes or prerequisites.

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

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

The description is front-loaded with the core action and each sentence contributes useful behavioral detail. It is slightly wordy and contains a typo ('restales'), but it remains concise 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 4-parameter tool with no output schema and only negative annotation hints, the description is nearly complete: it explains history depth, reversibility, and side effects on rendered clips. It stops short of describing return values or error conditions, but an agent has enough context to call the tool correctly.

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

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

The input schema already provides 100% parameter coverage with descriptions for project_id, segment_number, asset_type, and index. The tool description adds little parameter-specific meaning beyond restating that asset_type refers to image or video, so the schema carries the semantic load and the description earns a baseline 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 opens with a specific verb and resource: 'Restore a previously rendered version of a segment's image or video.' It clearly identifies what the tool acts on and how it differs from regenerating or updating assets, especially alongside the sibling regenerate_segment_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 gives clear context: a regeneration that turned out worse can be reversed by rolling back to an archived render. It does not explicitly enumerate alternatives or state when not to use it, but the intended use case is strongly implied by the 'regen that came out worse is reversible' framing.

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 prominently discloses that saving overwrites the active version and that the previous text is not kept, which is a destructive effect. However, the annotations declare destructiveHint:false, directly contradicting that disclosure; per the rubric this must score 1.

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

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

The description is long but not padded: it is organized into labeled sections for core behavior and each notation, and each rule prevents a mistake an agent could make. It could trim minor repetition, but the structure makes the length navigable.

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 core mutation behavior, ordering constraints, notation details, scan_script extraction consequences, and exceptions such as brackets inside narration. It is nearly complete, but the contradiction with destructiveHint and the absence of any return-value/result information leave a small gap for an agent.

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

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

Although the schema already documents both parameters (100% coverage), the description greatly expands the meaning of content by specifying the three notations: SCENE DIRECTIONS syntax and matching rules, break tags as the only pause mechanism with recommended durations, and speaker prefix format. This is far more than the schema alone provides.

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

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

The description opens with a precise verb and resource: 'Save script text', and immediately scopes it to both user drafts and edited versions of generated scripts. It also distinguishes the tool from siblings by stating that saving updates the active version rather than creating or switching versions.

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 an explicit workflow: fetch the current script with get_script before overwriting, use generate_script for new versions, activate_script_version for switching, and run scan_script afterwards. This tells an agent exactly when save_script is appropriate and what to do around 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 mark destructiveHint=true, but the description adds crucial behavioral detail: assets are recreated not merged, curated descriptions/reference images/voices are lost, directions are included in extraction but never leak into voice blocks, and the call is async returning {job_id}. This far exceeds what annotations alone provide and does not contradict them.

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

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

The description is front-loaded with the core purpose, then the critical destructive warning, then edge-case extraction behavior and post-call steps. Every sentence adds actionable information and none feel redundant or wasted.

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 destructive, async tool with no output schema, the description covers the important operational facts: job_id return, destructive re-run behavior, how directions are handled, and recommended follow-up actions. An agent has enough context to decide whether to call it and what to expect.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds some context about the active script and project scope, but it does not need to explain model or editable_sections because the schema already references list_models and get_section_template.

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 says exactly what the tool does: 'Analyze the active script: extracts character/environment/object assets and splits narration into voice blocks.' It names a specific verb and resources, and contrasts itself with rescan_voice_blocks, so an agent can distinguish it from siblings.

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

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

It explicitly warns that re-running is 'DESTRUCTIVE' and tells the agent to 'prefer rescan_voice_blocks after script edits.' It also gives follow-up guidance: 'Review list_assets afterwards and create_asset anything the video needs that neither narration nor directions ever name.' This is clear when-to-use and otherwise 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 indicate idempotentHint=true and destructiveHint=false, which the description doesn't contradict. Description adds context that it's a prerequisite binding, but lacks details on whether binding overwrites existing voices or affects other tools.

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?

Highly concise: two sentences that immediately state purpose and prerequisites with no superfluous words.

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

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

For a simple binding tool with no output schema, the description covers the essential purpose, prerequisites, and parameter sourcing. No gaps identified.

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 parameter descriptions. The description doesn't add new semantics beyond what's in the schema, 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 action ('Bind a TTS voice to a character asset'), the resource ('character asset'), and distinguishes from sibling tools like set_narrator_voice by noting the narrator's voice is 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?

Explicitly states when to use ('required before generate_voiceover for every character with dialogue') and when not to (narrator handled by set_narrator_voice). Also provides guidance on browsing IDs with list_voices.

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 the tool's role in the workflow and its prerequisite relationship with generate_voiceover. Annotations already provide idempotentHint and destructiveHint, so the description adds context about ordering and separation from character voices, which is sufficient transparency.

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 succinct sentences with no fluff. The description is front-loaded with the core action, followed by usage guidance and distinction from sibling tool. Every word earns its place.

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

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

For a simple two-parameter tool with complete schema annotations and sibling context, the description covers purpose, usage timing, alternative tool, and source of allowed values. No output schema is needed; the description is complete.

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

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

Schema coverage is 100%, and the description does not add new parameter information beyond what the schema already provides (e.g., 'voice_id' description in schema already mentions list_voices and provider matching). Baseline 3 is appropriate as the description does not enhance parameter semantics.

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

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

The description clearly states the action: 'Set the project's narrator TTS voice'. It distinguishes from the sibling tool set_character_voice by noting that character dialogue voices are separate. The verb-resource pairing is 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?

Explicitly states when to use the tool: 'required before generate_voiceover whenever the script has narration.' It also directs users to browse voice IDs with list_voices and clearly separates narrator voices from character voices, providing a when-not-to-use scenario.

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 explains that the set style's fields drive generations, adding behavioral context beyond annotations. Annotations already indicate non-destructiveness and idempotency; the description adds that this affects generation output. A higher score would require explicitly mentioning idempotency or side effects like permission requirements.

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, efficient and direct 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 two-parameter tool with no output schema and good annotations, the description is complete: it explains purpose, usage timing, and effect on generations. 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% with detailed parameter descriptions. The tool description adds no extra parameter meaning; it repeats that style comes from create_style/list_styles and project from create_project/list_projects, already in schema. 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 sets a project's default style, specifying that this style's art/narrative/director fields drive generations. This distinguishes it from siblings like create_style (creates a style) and update_style_fields (updates style properties).

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 usage guidance: 'Use after create_style to put a new visual identity into effect, or to switch a project between channel styles.' This tells when and why to use it, and implicitly contrasts with alternatives like create_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?

Annotations indicate idempotent and non-destructive; the description adds that the key is encrypted at rest, providing additional context 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?

Two concise sentences with purpose 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?

Given the simple tool with full schema coverage and annotations, the description covers usage context (BYOK plan, zero credits) adequately. No output schema 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 coverage is 100%, so baseline is 3. The description reiterates the provider list and encryption but adds minimal new meaning; schema already covers param details.

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

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

The description clearly states the action ('Register') and resource ('BYOK provider API key'), and distinguishes from sibling tools like 'list_provider_keys' by specifying the operation type and constraints (encrypted at rest, BYOK plan only).

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 notes the requirement for a BYOK plan and explains the consequence (jobs charge 0 credits). It lists valid providers. While it doesn't mention alternatives, the context is sufficient for when 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?

The description adds behavioral context beyond annotations: the reference is applied at generation time, and image must be regenerated. Annotations indicate idempotentHint=true (safe to retry) and destructiveHint=false, 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?

The description is a focused paragraph with all essential information, no filler. It could be slightly more structured (e.g., bullet points), but it is easily readable and front-loads the main 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 has 3 parameters, no output schema, and annotations provide idempotentHint, the description covers the core behavior, parameter intent, and post-requisites (regenerate image). It is complete enough 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 coverage is 100%, but the description adds value by explaining 'continues_from' in practical terms: '1-based number of the EARLIER segment' and 'pass 0 to clear the link'. For 'segment_number', it reiterates the 1-based nature and references 'get_segments'. This clarifies ambiguous numeric values.

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: making a segment's image render as a continuation of an earlier segment's frame. It mentions key concepts like 'continues_from_segment' and 'settable after the fact', with concrete examples. This distinguishes it from sibling tools like 'split_segment' or 'combine_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 explicit usage guidance: what 'continues_from' represents, how to clear the link with 0, and the need to regenerate the image afterwards. However, it does not explicitly state when not to use the tool or mention alternative tools, though the context makes its niche 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?

Beyond the destructiveHint annotation, the description discloses important side effects: non-inherited parts start fresh, the inherited part's rendered clip goes stale and must be re-rendered, and later segments renumber. This is exactly the behavioral depth needed for a destructive editing operation.

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

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

The description is four short, information-dense sentences, each carrying distinct value: core action, inheritance behavior, freshness consequence, and renumbering warning. It is front-loaded, with no filler or redundant restatement of the tool name.

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?