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?

The description adds a useful behavioral detail beyond the annotations: the effect lands on the segment's scene immediately and does not require build_scenes. However, it does not disclose whether calling it again replaces an existing SFX or stacks another one, which matters for a mutating tool with idempotentHint=false.

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 tight sentences with no filler. The main action is front-loaded, the parameter lookup hint is embedded compactly, and the important immediate-effect behavior is stated last.

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 three-required-parameter tool with no output schema, the description gives the agent enough to select and invoke the tool correctly: what it does, where to get the track ID, and what happens after the call. The main omission is behavior around repeated calls or replacement semantics.

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 fully documents project_id, segment_number, and library_track_id. The description adds little beyond what the schema says, except reinforcing that the track ID comes from browse_audio_library with category='sfx'.

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

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

The description uses a specific verb ('Attach'), a specific resource ('a sound effect from the audio library to a segment'), and names the source library lookup path. This clearly distinguishes it from siblings like add_music_track or update_segment_content.

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

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

It explicitly tells the agent how to obtain the required track ID via browse_audio_library(category='sfx') and that no build_scenes step is needed afterward. It does not explicitly name an alternative like add_music_track for music, so it falls just short of full when-to-use coverage.

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?

Annotations are minimal (no readOnly/idempotent/destructive hints), so the description carries the full burden. It discloses that the call is synchronous, returns summary/mutations/skipped_mutations (with a warning to check skipped_mutations), and that scene ids change after segment edits – important behavioral context beyond annotations. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: scope, exclusions, return behavior, addressing rules, duration constraint, and alternative tools. It front-loads the primary purpose and packs the rest efficiently without fluff.

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

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

For a mutation tool with five parameters and no output schema, the description covers all critical operational details: what can/can't be edited, return values and their significance, scene addressing, and when to use alternatives. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds semantic value by explaining the preferred addressing method (project_id+segment_number) and why scene_id should come from a fresh list_scenes call (because ids become stale). This goes beyond the schema's basic descriptions.

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

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

The description opens with 'Edit ONE scene with a natural-language note' – a specific verb, resource, and mechanism. It enumerates example actions (move/restyle/add/remove layers, overlays, change motion) and distinguishes itself from siblings by explicitly naming project_director_note for whole-video notes and remove_segment_asset for direct deletions.

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 when-to-use and when-not-to-use guidance: 'for whole-video notes, project_director_note' and 'remove_segment_asset deletes an SFX or overlay by id without a model in the loop.' It also sets exclusions (storyboard/video/voiceover layers can't be removed) and a hard constraint (scene durations locked to narration, don't shorten/extend except final scene), plus how to address the scene (project_id+segment_number preferred, scene_id from a fresh list_scenes call).

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 declare write/non-idempotent/non-destructive, but the description adds the key traits beyond them: the call is async, the job writes the image back onto the asset row, and the server enforces the prerequisite ordering. It does not mention cost or failure/retry behavior, which is the one remaining gap for an image-generation job.

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?

Purpose is front-loaded in the first clause and every sentence carries information (role, prerequisite, ordering, verification loop). It is dense and slightly instruction-heavy, but no sentence is 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?

With no output schema, the description usefully explains where the result lands and how to verify it (view_image the file_path) plus the correct batching pattern. It is nearly complete for a 4-param async job, though cost/time expectations are unaddressed.

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 model, settings, and editable_sections are already documented in the schema. The description adds no parameter-level detail (e.g., guidance on which model or section overrides to use), so the baseline 3 is correct.

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

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

States a specific verb and resource ("Render an asset's reference image") plus the scope (in the channel's art style) and the artifact's role as a cross-shot visual anchor. An agent can distinguish this from generate_voiceover, regenerate_segment_asset, and create_asset without opening any schema.

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 it must be used ("EVERY character, environment, and object asset needs one before generate_voiceover"), that the server enforces this ordering, and names the follow-up tools (await_jobs, list_assets, view_image). Nothing about sequencing is left to inference.

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

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

The description discloses 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?

Annotations indicate no read-only, open-world, idempotent, or destructive hints, so the description must disclose behavior. It reveals non-idempotence for regeneration (re-billing), explains idempotent gap-filling (skips existing), and notes automatic re-alignment of segment timings. It also mentions async behavior. This adds significant 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?

Dense but well-structured: the first sentence states the core, then critical safety and regeneration semantics, then prerequisites and side effects. Slightly long but each clause carries information; no redundant sentences.

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

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

Given the tool's complexity (two modes, async, side effects) and lack of output schema, the description covers essential usage, pitfalls (re-billing), and post-condition (await_jobs). It might omit error cases or exact response shape, but these are not critical for invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond by clarifying the dual semantics of voice_block_ids (omit vs pass) and explaining how editable_sections/settings apply to every selected block. It also directs to get_section_template and list_models for valid keys, adding value.

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

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

The description clearly states the tool's purpose: generating TTS audio for voice blocksians, with a specific verb (generate), resource (voice blocks), and distinct modes (fill gaps vs regenerate). It differentiates from siblings like set_narrator_voice and update_voice_block by focusing on audio generation.

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

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

Provides explicit guidance on when to use each mode: omit voice_block_ids to fill gaps safely, or pass them to regenerate. It also states a prerequisite (voices must be bound) and references sibling tools for setup. This is comprehensive routing.

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 declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds substantial behavioral context: it explains the meaning of the `continues_from_segment` field (continuation vs. fresh shot), the pagination behavior (limit/offset, 0 returns all), and that each segment's assets include overlays. It also discloses the return shape {total, offset, returned, segments}. No contradictions with annotations.

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

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

The description is longer than typical but every sentence contributes: it covers the return shape, pagination, the continuation semantics, and the overlay auditing capability. It is front-loaded with the core purpose, and the subsequent paragraphs expand on important behavioral details without redundancy. It earns its length given the tool's complexity.

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

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

For a read-only listing tool with three parameters, no output schema, and rich annotations, the description covers everything an agent needs: the return structure, the pagination pattern, the special meaning of a field, and how the result relates to other tools. The description is complete enough to call the tool correctly without additional 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%, so the parameters are already described. The description goes beyond the schema by explaining the pagination intent ('page through with offset/limit rather than fetching all segments') and clarifying that segment_number (not a parameter here) is the handle for other tools. It reinforces the meaning of limit/offset without repeating the schema text verbatim, adding contextual value.

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

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

The description opens with a specific verb ('List') and resource ('storyboard's segments'), then enumerates the returned fields (narration span, type, duration, creative direction). It explicitly states that segment_number is the handle used by all segment tools, and distinguishes itself from sibling tools like get_segment_assets by noting it is the one call that audits every overlay. This clearly separates it from the get_segment_assets 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?

The description gives explicit guidance on when to use this tool: to list segments and to audit overlays, and it tells the agent to page through large projects with offset/limit rather than fetching everything. It also points to set_segment_continuation for adjusting the continuation field, giving an alternative action. No ambiguity about when to use it versus other list tools.

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

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

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 cover the safe read-only profile, yet the description adds substantial behavior beyond them: the deterministic default-resolution order (saved expert-drawer choice > account default > first entry), personalization ordering, family-level personalization, and the hard constraint that a voice_block model must match the project's voice_tts_provider or generate_voiceover rejects it. That last item is a cross-tool failure condition an agent cannot infer elsewhere.

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?

Purpose is front-loaded in the first sentence, and the remaining lines each carry distinct information (defaults, personalization, family behavior, provider constraint). It is dense and slightly clause-heavy, but no sentence is 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?

With no output schema, the description compensates by describing the returned data (display names, credit estimates, per-model settings_schema) and how entries are ordered. Combined with full param coverage, an agent has everything needed to call and interpret this 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, but the description adds meaning not in the schema — chiefly the default-resolution behavior when `job`... is unspecified, and the rationale for the optional family params. It reinforces rather than merely repeats the schema's own lip_sync/provider hints.

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

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

States a specific verb and resource ('List the models allowed for a generation job') and goes further to enumerate what the listing contains (display names, credit estimates, settings_schema). This clearly separates it from sibling list_* tools like list_voices/list_styles and tells an agent it is the model-enumeration call for a job.

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?

Explains the selection semantics when `model` is omitted and, more importantly, states when to pass the family parameters (lip_sync for segment_video, provider for voice_block) and why — 'personalized only when you name the family'. It does not name alternative tools or explicit exclusions, but the when-to-pass guidance is concrete and actionable.

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

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

Annotations already declare readOnlyHint=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?

The description discloses several non-obvious behaviors beyond the sparse annotations: a routing pass selects applicable scenes, the call is synchronous with a few seconds per scene, there is a hard limit of 10 scenes, and the return value is per-scene results with summary and mutation_count. This fully carries the behavioral burden since all annotations are false.

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

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

Three sentences, each earning its place: the first states purpose, the second states the routing constraint and alternative, the third states behavior and return shape. The most important scoping information is front-loaded.

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

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

For a tool with no output schema and all-false annotations, the description covers purpose, constraints (10 scenes), synchronous timing, and return fields. It could additionally mention error cases or what happens when no scenes match, but it is already sufficient for an agent to call it correctly.

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

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

Schema coverage is 100%, with both parameters already well-described: 'message' has natural-language examples and 'project_id' explains its origin. The description reinforces that 'message' is project-wide in scope but does not add any new parameter-level detail beyond the schema, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource: 'Apply a project-WIDE director note', with concrete examples like 'make the intro punchier'. It also differentiates itself from the sibling 'director_note' by explicitly framing the scope as project-wide, so an agent can tell them apart immediately.

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 a clear condition for when to repeat calls or fall back to the alternative: 'at most 10 scenes per call, so a change touching more needs repeat calls or per-scene director_note'. It identifies the sibling tool and a limiting constraint, though it could be more explicit about preferring per-scene director_note for single-scene edits.

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?

While annotations already flag destructiveHint=true, the description adds that it removes the asset and every scene layer built from it, immediately. This goes beyond the annotation by revealing cascading effects and the lack of reversal.

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 primary action and scope, no filler. Every phrase adds meaning.

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 destructive tool with no output schema, the description covers the action, the asset types, the condition for asset_id, and the immediate cascading effect. Minor gap: no mention of errors or confirmation, but not necessary given 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 coverage is 100%, so baseline is 3. The description adds value by explaining when asset_id is optional and where to obtain it (get_segment_assets), which the schema only partially implies.

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 the action (delete), the resource (segment's sound effect or overlay), and clarifies scope by explicitly excluding structural assets (image, video, voiceover). This clearly differentiates it from siblings like delete_asset 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?

It states when to use: for SFX/overlay only, and when not to use (structural assets). It also gives a conditional rule for asset_id (no id needed when only one attached). It doesn't name alternatives explicitly but gives enough contextual guidance.

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

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

The description 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 explicitly discloses that the previous text is not kept, which is critical behavioral context beyond the annotations. It also details that scene directions, pauses, and speaker prefixes are never spoken, and it documents how pauses truly behave versus ellipses/dashes. This is highly transparent about side effects and edge cases.

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 the length is earned: it is organized into labeled sections with bolded terms and contains no filler. It is front-loaded with the core behavior before diving into notation details, though a slightly tighter presentation would be possible.

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

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

The description is contextually complete for a complex update tool: it covers preconditions, post-actions, destructive overwrite behavior, related sibling tools, and the exact syntax of the three script notations. The lack of an output schema is not a gap because the description fully explains the operation's contract.

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 covers both parameters, the description substantially enriches the `content` parameter by specifying exact notation syntax and rules: `[SCENE: ...]` paragraphs, `<break time="1.5s" />` tags, and `Name:` speaker prefixes. It also warns against malformed uses like two breaks back-to-back, which the schema alone does not convey.

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 an explicit verb and object: 'Save script text' and clarifies that saving 'UPDATES the active version in place.' It also differentiates itself from related tools like generate_script and activate_script_version by describing their roles in the same workflow.

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

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

The description gives concrete workflow guidance: show the user get_script before overwriting, run scan_script afterwards, and notes that new versions come from generate_script while activate_script_version switches between versions. This makes both when-to-use and when-not-to-use 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 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.