framesail

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description's added value is the fallback semantics (defaults only apply when nothing else names a model) and the per-family independence ('each family keeps its own default'). These are genuine behavioral traits not derivable from the annotations. It stops short of 5 by not addressing what clearing a default reverts to or any auth/scope constraints.

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?

It is short and each sentence carries information, so it is not padded. But the opening is a grammatically incomplete fragment that describes the resource rather than front-loading the action, which slightly obscures the tool's purpose at first read.

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 6-parameter edit tool with full schema coverage, no output schema, and annotations that cover the safety profile, the description supplies the missing semantics: fallback behavior and conditional parameter requirements. It is close to complete, lacking only error/reset behavior when a default is cleared.

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 per-parameter meanings are already documented (baseline 3). The description adds cross-parameter conditional requirements — 'voice_block needs provider' and 'segment_video needs talking_head' — which the flat per-parameter schema descriptions do not express. That is real added value 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 title ('Edit account') and the phrase 'The account's default model and settings for one kind of generation' together convey that this sets account-level defaults for a generation family. It is clearly distinguishable from siblings like editor_edit or segment_edit, which operate on other scopes. The opening is a noun fragment rather than an explicit verb+resource statement, so it stops short of 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?

'used when neither the call nor the item's prompt editor names one' explains the fallback context in which these defaults matter, which is useful. However, it never states when an agent should invoke this tool versus the many *_edit siblings, nor any preconditions for calling it. Usage is implied rather than directed.

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 disclose non-readOnly, non-destructive, non-idempotent behavior, so the bar is lower. The description adds genuine workflow context: a description change must be followed by re-rendering the reference image via assets_generate. It omits permission/auth requirements and what the update does to existing renders, but the downstream-invalidation note is real added value.

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

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

Two tight sentences: the capability first, then the required follow-up action. Every clause earns its place and nothing is padded.

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

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

No output schema exists, but the description supplies the critical post-edit workflow (regenerate the reference image) that an agent would otherwise miss. For a mutation tool with full schema coverage and annotations, this is complete enough, though it could note what the operation returns.

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 fully documents all six parameters, including the action enum's per-action requirements. The description only restates name/description edits at a high level and adds no syntax or format detail beyond the 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?

States specific verbs (add, rename, rewrite) against a specific resource (assets: character/environment/object), which distinguishes it clearly from assets_read and assets_generate. The reference to 'Analyze Script missed' gives the concrete scenario the tool exists for. An agent can tell it apart from its siblings 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?

Gives a clear when-to-use trigger (when Analyze Script missed an asset) and names the follow-up alternative (assets_generate) for re-rendering reference images. It does not explicitly contrast create vs update behavior in prose, but the schema enum covers that split. Clear context with no strong exclusions stated.

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

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

Annotations cover the mutation/safety profile, and the description adds real behavioral value beyond them: the style-template prerequisite, the dedupe of assets already rendering, and the billing guarantee that a repeat never bills twice. It does not describe failure handling or timing, so not a 5.

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, front-loaded with the purpose before prerequisites and follow-up. Minor redundancy between 'skipping ones already rendering' and 'a repeat never bills twice', but nothing wasted overall.

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 non-destructive mutation with full annotation coverage and no output schema, the description supplies the prerequisite, default-omission behavior, billing/dedupe semantics, and a verification step. It omits only secondary details like timing and error 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 description coverage is 100%, so the baseline is 3. The description restates asset_ids omission behavior (render every asset with none) and adds the style-template requirement, but adds little on model, settings, editable_sections, or dry_run beyond what the schema already says.

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 (render) and resource (reference images) and explains their role: keeping characters/environments/objects consistent across segments. It names the sibling view_image as a follow-up step, though it does not explicitly contrast itself with style_generate or storyboard_generate.

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 a precondition (both style template images needed) and a follow-up workflow (view_image to check likeness), plus the effect of omitting asset_ids. It stops short of naming an explicit alternative tool to use instead for a different case.

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

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

Annotations already establish readOnly, idempotent, non-destructive behavior, so those need not be restated. The description adds genuine value beyond them: it explains that description is 'what every render follows', that a null reference_image means 'not rendered', and that voice_id exists only for characters.

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 compact lines that front-load the resource and then enumerate the returned fields. Every clause carries information; no filler. Slightly dense phrasing, but appropriately sized.

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 return-shape burden and does so well, naming the fields each asset returns and their meaning. For a simple two-parameter read tool this is sufficient for an agent to call and interpret 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%, so project_id and asset_type are already documented by the schema (including the 'Only this kind' filter). The description echoes the three asset kinds but adds no syntax or filtering detail beyond what the schema provides, so the baseline 3 applies.

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

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

The description identifies the resource (the project's characters, environments and objects) and what each carries, and combined with the name/title it is clearly the read operation. It does not explicitly name that it reads versus its siblings (assets_edit, assets_generate), but the returned-field detail makes 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?

There is no explicit when-to-use versus assets_generate or assets_edit, but the parenthetical 'reference_image (null: not rendered; view_image it)' routes the agent to a sibling tool conditionally. The closing domain rule ('Each needs a reference image before the voiceover') hints at when this data matters but is not framed as 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?

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, but the description adds genuinely new behavioral detail: the operation is permanent and irreversible, requires user confirmation, and cascades (deleting a project removes everything in it; segment_extra removes scene layers). It does not discuss failure modes or partial-failure behavior, which keeps it from a 5.

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 critical irreversible/confirm warning is front-loaded in the first sentence, and every following clause carries type-specific information. The hard line-wrap formatting (breaks mid-sentence and mid-phrase) makes it slightly harder to scan than a flowing paragraph, but there is no filler content.

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

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

For a destructive, non-idempotent tool with no output schema, the definition covers what gets destroyed, the confirmation requirement, cascade scope, and unsupported targets. What is missing is post-deletion feedback (what the caller receives, how to verify success), which is a modest gap given annotations already flag destructiveness.

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 baseline is 3, but the description goes further by giving semantic meaning to the enum values ('asset: a character, environment or object', 'music_track: a background music track'), which the schema only labels. It still relies on the schema for id/project_id/segment_number mechanics, so it is not a 5.

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

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

Opens with a specific verb+resource ('Permanently delete') and then enumerates exactly what each supported type removes (project, asset, music_track, segment_extra). The per-type breakdown lets an agent distinguish this destructive tool from siblings like assets_edit, segment_edit, or storyboard_edit 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?

Gives a clear precondition ('irreversible, so confirm with the user first') and an explicit exclusion ('a segment's image, clip and voiceover can't be deleted'), which steers the agent away from unsupported calls. It stops short of naming alternative tools for removing those unsupported artifacts, so it is not a full 5.

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

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

Beyond the annotations (destructive/not idempotent), the description adds substantial behavioral context: edits spend credits, returns include a skipped_mutations list with applied/reason that the agent is told to check, project_note affects up to 10 scenes per call, scene lengths follow narration, and image/clip/voiceover layers cannot be removed. This is exactly the surplus detail the annotations cannot convey.

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

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

The one-line purpose is front-loaded before the dense action breakdown, and every clause carries information (credits, return shape, layer constraints). It is a single semicolon-heavy block rather than cleanly separated sections, which slightly hurts scanability but there is little 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 13-parameter, destructive, credit-spending tool with no output schema, the description covers the key gaps: credit cost, the skipped_mutations return and its semantics, per-action limits, and layer constraints. It omits auth/permission requirements and the return shape beyond skipped_mutations, so it is strong but not exhaustive.

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 baseline is 3, but the description adds meaning not fully in the schema: captions act as a merge, music is timed in seconds and a track's duration follows from its trim, and the action-level parameter groupings mirror the enum. That extra semantic framing lifts it above baseline.

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

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

The description states a specific resource (the video in the editor) and enumerates the six distinct actions it can perform (scene_note, project_note, captions, add_sfx, add_music, update_music), so an agent can tell the scope apart from a read tool. The opening 'Polish the video' is generic, and it never explicitly names sibling tools like editor_read as the reading counterpart, so it stops short of 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?

Each action is tied to a clear condition: scene_note for one scene, project_note for the whole video (10 scenes per call), captions to merge settings, add_sfx to attach a sound effect, add/update_music for background music. However it gives no explicit 'when not to use this' exclusion or direct routing to editor_read/segment_edit 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 readOnly/idempotent/non-destructive, so the bar is lower, yet the description still adds real behavior: the paginated scenes shape, music timing in seconds, and the notable fallback where an empty audio_library match returns the library's moods and genres. It does not disclose auth or rate-limit traits, but those are minor here.

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 tight, action-scoped clauses with no filler or repetition. It is slightly under-structured at the front, opening on 'scenes:' rather than a one-line statement of what the tool is, forcing the reader to assemble overall purpose from name and 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?

With 9 parameters and no output schema, the return-shape details (scenes object with total/offset/returned, music tracks, fallback listings) carry useful load, and the action enum covers the three modes. What is missing is only light framing (prerequisites for project_id, pagination guidance) already handled by the 100%-covered schema.

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

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

Schema description coverage is 100%, so every parameter (including the action enum, mood, genre, limit, offset, search, category, include_composition) is already documented in the schema. The description adds return-format context ('timed in seconds') but little that clarifies the parameters themselves, so the baseline 3 applies.

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

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

The description enumerates the three actions and what each returns (scenes timeline, music tracks, audio_library tracks), so the resource is identifiable per action. It never states the top-level verb+resource explicitly (the reader infers 'read editor data' from name/title), and only partially differentiates from siblings by naming editor_edit for the audio_library case.

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?

There is implicit routing: audio_library results are 'tracks to add with editor_edit', which frames this as the read counterpart to the edit tool, and the no-match fallback (listing moods/genres) is noted. But there is no explicit 'use this when you need to inspect X' statement or clear when-not guidance across the three actions.

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 non-read-only, non-destructive, non-idempotent, so the safety profile is already covered. The description adds real value beyond that: the operation is asynchronous (an 'export job' that 'completes' later) and the output surfaces through get_status rather than the immediate response, plus it is 'free', a cost signal annotations cannot convey.

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

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

Two short clauses, front-loaded with the action and its source timeline; nothing is padded. The 'free' note and the async follow-up pointer both earn their place, though the sentence could be tightened slightly.

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, and the description correctly fills that gap by telling the agent the export_url arrives via get_status rather than in this call's response. For a single-parameter, non-destructive tool this is nearly complete; only the relationship to the 'render' sibling is 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% with a single required 'project_id', so the schema carries the parameter documentation. The description adds no format, constraint, or sourcing detail for project_id, so the baseline 3 applies.

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

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

States a specific verb and resource ('Render the finished video from the editor timeline'), which is clear on its own. However, the sibling list contains a tool literally named 'render', and the description never distinguishes export_video from it, leaving ambiguity about which one produces the final deliverable.

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 is implied rather than stated: call this when you want the finished video. It does name get_status as the follow-up step, which is helpful workflow context, but there are no explicit when-not conditions and no explanation of how it relates to the 'render' sibling.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds substantive context beyond that: credit estimates are returned, settings_schema exposes the valid settings keys, is_default reflects the account's saved choice falling back to Framesail's, and entity_backed=true sections cannot be overridden here and must be changed via edit tools — a real mutability boundary.

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?

It is information-dense and front-loaded with the core purpose, with no filler sentences. The parenthetical packing ('settings_schema (the valid settings keys)') and fragmentary opening slightly reduce readability, but every clause carries useful signal.

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, so the description must explain the return values, and it does: model lists with credit estimates and settings schema, the is_default flag, and prompt_sections with their entity_backed semantics. The top-level response shape is not spelled out, but the fields an agent needs to act on are covered.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely elaborates: it explains what is_default means, what settings_schema contains, the model-family concept behind provider/talking_head, and the entity_backed flag that governs editable_sections. That is added meaning beyond the enum descriptions in 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 makes clear this is a discovery/read tool returning the options a generate call can accept (allowed models with credit estimates, settings schema, prompt sections), which cleanly separates it from the many *_generate siblings that actually produce assets. The opening sentence is a fragment ('What a generate call can be told to use') rather than a verb+resource statement, so it is clear but not maximally crisp.

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 conditional guidance tied to the parameters ('pass provider or talking_head for one family') and routes the agent to the alternative tool set for a specific case ('entity_backed=true sections ... change it with the edit tools'). It does not explicitly say when not to use this tool or that it should be called before a generate call, 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 cover the safety profile (readOnly, idempotent, non-destructive). The description adds real behavioral context beyond them: the degraded no-API-access path returning subscription_needed, and the instruction to pass that on. It does not mention rate limits or pagination, but for a status read the disclosure is solid.

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 text is dense and front-loaded with the entry-point instruction, and each sentence carries new information about a different scope. The opening metaphor is slightly wasteful, but overall there is little 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 must convey return values, and it enumerates the key fields (plan, credits, credits_available, step states, web link, export_url, next_step, subscription_needed). It is nearly complete for the account path; the project and channel paths are described by key names rather than structure, which is a minor gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further by explaining what each parameter yields (project_id adds settings/step states/jobs/export_url/next_step; channel_id reports channel style keys), giving outcome-level meaning that the terse schema descriptions ('Project id', 'Report this channel's style') do not.

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

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

The opening line is vague and metaphorical ('Where things stand and what to do next'), but the body states a specific resource (account status: plan, credits, credits_available) and distinguishes the three scopes (account, project_id, channel_id). An agent can tell it apart from projects_read or style_read once it reads past the first sentence.

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?

'start and resume here' tells the agent to call this first or to resume a workflow, and the body explains the conditional branches (project_id vs channel_id vs no API access). It stops short of naming explicit alternatives among siblings, but the context of use 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 cover safety (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower. The description adds genuine behavior beyond them: new projects inherit channel style, the style prerequisite, and that a web_url is returned for the user to follow — all useful side-effect 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?

Three tight sentences with the mutation scope front-loaded, followed by the dependency and the follow-up instruction. No repetition or filler, though it could be slightly more ordered around the action enum.

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 multi-action mutation tool with no output schema, the description covers scope, prerequisite, and return signal (web_url). An agent has enough to invoke it correctly; remaining gaps are minor given the rich schema and 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 description coverage is 100%, so the schema already documents every parameter including the action enum semantics. The description only echoes title/brief/video_format, adding no syntax or format detail beyond the schema; baseline 3 applies.

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

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

The description gives a concrete verb set (create/change) and the exact resources and fields affected (channel, project, title, brief, video_format). An agent can distinguish it from projects_read by the mutation framing, though it never names the read sibling explicitly.

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 supplies a real workflow prerequisite: a channel with no style needs style_edit action=create before anything is generated, and it tells the agent to surface the returned web_url. No explicit when-not or negative routing to alternatives is given, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds nothing beyond that — no statement of scope, pagination, or what a caller gets back for either action. It is effectively a restatement of the title.

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?

Six words, nothing wasted — but it is a sentence fragment that omits the verb, so brevity comes at the cost of clarity. It is front-loaded but under-specified for a two-action 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 two-parameter read with full schema coverage and rich read-only annotations, the definition is minimally adequate — an agent can call it. What is missing is any guidance on selecting between the channels and projects actions and any hint of the return shape, since no output schema exists.

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%; both action and channel_id are documented with their semantics ('channels: your channels; projects: the projects in channel_id'). The description's clause 'or the projects in one channel' only loosely echoes channel_id and adds no format or constraint detail beyond the schema. Baseline 3 applies.

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

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

The description is a noun phrase ('Your channels, or the projects in one channel') rather than a verb+resource statement; the verb is only recoverable from the title. It does identify the two resources (channels, projects) and their nesting relationship, but it does not distinguish itself from sibling projects_edit or projects_read-style operations on its own.

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 when-to-use guidance, no mention of which of the two actions to pick in which situation, and no mention of the sibling projects_edit that operates on the same resource. The only routing signal is buried in the action enum description in the schema.

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

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

Annotations only declare the generic safety flags (destructiveHint=false, idempotentHint=false). The description adds high-value behavior beyond them: this is the biggest credit spend, dry_run quotes the estimate, animate defaults to a clip or talking-head model, a refused render leaves the segment unchanged, and there is a documented recovery path (segment_restructure change_type=to image keep_image=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?

Front-loaded with the critical instruction to run dry_run first, and each subsequent sentence carries distinct operational content. It is dense, multi-clause prose, but almost 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?

For a 10-parameter mutation tool with no output schema, the description covers cost/estimation behavior, refusal handling, defaults, and post-run verification paths, which is what an agent needs. Nothing essential for correct invocation appears 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 baseline is 3, but the description adds cross-parameter semantics the schema does not: overrides need segment_numbers plus what=images/clips, and animate uses segment_number with optional talking_head. It leaves a few params (model, settings, editable_sections) to the schema alone.

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 (render) and resource (segment images and clips) and immediately distinguishes its two sub-actions, generate and animate, with the scope of each. It also flags the differentiating stakes ('the biggest spend in the video'), which no sibling touches.

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 when-to-use and when-not: dry_run=true first and get user confirmation; generate without segment_numbers = everything not yet rendered, with them = those segments including finished ones; overrides require segment_numbers and what=images/clips. It also routes to verification via storyboard_read action=segment_assets and view_image.

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

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

Goes well beyond the annotations (destructiveHint, non-idempotent) by disclosing the concrete consequence: the old text is lost and should be surfaced first, revise spends credits, and revise returns revised_text without persisting. This is exactly the kind of consequence detail an agent needs before calling a destructive tool.

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?

Core purpose and the destructive warning are front-loaded in the first two sentences; per-action blocks follow. The notation paragraph is dense and run-on, but its rules are operationally relevant to authoring `content`, so little of it is genuinely 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 9-parameter, 5-action tool with no output schema, the description covers the risky paths (save overwrite, credit-spending revise, non-persisting revise return) well. The remaining gap is that settings and set_concept get no behavioral treatment beyond the schema's action enum mapping.

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 real meaning the schema cannot carry: the notation grammar for `content` (SCENE blocks, break tags, dialogue naming, inline delivery cues) and the revise/selected_text splice workflow. It leaves the settings and set_concept fields to 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 opening line states a specific verb+resource ('Change the script or its settings') and adds a differentiating cost note ('only revise spends credits') that separates it from script_generate/script_read. It does not explicitly name a sibling, so it lands just short of 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?

Gives per-action guidance (save replaces the active text; activate_version switches versions; revise rewrites without saving and must be spliced in then saved) and a prerequisite ('show the user the current script first'). Clear context, though it never explicitly routes to siblings like script_read for ids beyond a passing mention.

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 non-readOnly, non-idempotent, non-destructive, and the description is consistent with them while adding real behavioral detail: each run creates a new version, and analyze preserves existing assets (description, reference image, voice) and adds new ones while stale assets persist until the user deletes them. That side-effect disclosure goes meaningfully beyond the structured fields, though permissions and failure behavior are unstated.

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 two modes are front-loaded and labeled, and the follow-up read tools are attached to the relevant mode. The parenthetical about [SCENE: ...] directions is useful but slightly dense; overall it is tight and earns its length.

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

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

For a two-action mutation tool with full schema coverage and no output schema, the description covers what each action does, how versions behave, what analyze does to existing assets, and which read tool verifies each result. 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 description coverage is 100%, so the schema already documents model, settings, project_id, and editable_sections. The description enriches the meaning of the `action` enum values considerably, but says nothing about the other four parameters, so it only marginally exceeds 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 names the two modes explicitly (generate: write the script; analyze: find characters/environments/objects and split into voice blocks), giving a specific verb+resource for each. It also names the sibling tools used to inspect results (script_read, assets_read), so an agent can place it in the workflow without opening the 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?

It tells the agent what each action is for and how to follow up (review with script_read, review assets with assets_read), plus the important context that each generate run produces a new version. It does not address when to prefer script_edit over re-generating, nor any prerequisites, so the routing guidance is clear but not exhaustive.

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

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

Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description goes beyond them by enumerating the payload contents (active script, versions, settings) — meaningful given there is no output schema — though it says nothing about size, versioning behavior, or what happens when no script exists.

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?

Very short and dense: payload contents first, then the user-facing directive. The parenthetical field list is slightly cluttered but every element carries information; no filler sentences.

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

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

For a single-parameter read tool with full annotation coverage, the description covers what it returns and when in the workflow to invoke it. With no output schema, a bit more detail on the returned shape (e.g. empty/absent script case) would be needed for a 5, but 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 coverage is 100% with a single project_id parameter, so the schema already carries the parameter documentation. The description adds no additional meaning about project_id (format, source, or scoping), which is the expected baseline when the schema does the work.

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?

Names the exact resource returned — the active script, its versions, and script settings with three named setting fields — so an agent knows precisely what this fetches. It is phrased as a noun list rather than a verb+resource statement, but the read intent is unambiguous and it is distinguishable from script_edit and script_generate by naming script content rather than changes.

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

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

"Show the script to the user before Analyze Script" supplies one workflow cue and a sequencing constraint, which is real guidance. However, it never names the sibling tools (script_edit, script_generate) or states when-not to use this versus those, so the routing information is only partially 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?

Goes well beyond the annotations: 'only split spends credits', set_prompts leaves renders unchanged until re-rendered, rollback is itself undoable and preserves the prompt-editor model, split leaves non-inheriting parts empty and auto-writes prompts from narration (spending credits), and later segments renumber requiring a fresh storyboard read. That is exactly the side-effect and cost disclosure an agent needs.

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 lead sentence front-loads the key constraint (no render loss except split) and the 'Returns the changed segments' clause covers the absent output schema. The action paragraphs are dense but each earns its place; a bulleted structure would read better than the current run-on lines.

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 11-parameter, four-action mutation tool with no output schema, the description covers costs, reversibility, ordering side effects (renumbering), and the return value. The main omission is any routing guidance versus segment_restructure and storyboard_edit.

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, but the description adds meaning the schema does not: it links each action to its parameters conceptually (e.g., the inherited part keeping prompts for inherit_index, continuation meaning 'same composition, only the change') and clarifies that split inheritors 'start empty' until prompts are written.

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+resource ('Change one segment') and then enumerates four distinct actions (set_prompts, set_continuation, rollback, split) with their effects, so an agent understands the tool's scope well. It does not differentiate itself from the sibling segment_restructure, which is the only real gap.

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?

Each action carries its own when-to-use context: set_prompts for verbatim prompt writes with unchanged renders, set_continuation for chaining an earlier image, rollback for undoing to one of the last 5 renders, split for cutting into 2-4 parts. It never names an alternative sibling tool or states when NOT to use this one, 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?

Far exceeds the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=false): it discloses the preview-first contract, the confirm=true gate, the 409 refusal while background AI runs, credit spend, what renders survive or go stale, retiming of kept renders, and renumbering of later segments.

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?

Long but front-loaded: the preview/confirm workflow comes first before per-action detail. Each paragraph is organized by action and every sentence carries operational content, though the density is close to the upper limit of comfortable scanning.

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

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

For a 9-parameter destructive mutation with no output schema, the description covers the preview return ('returns what would be lost'), the refusal mode, async background steps, credit cost, and downstream effects. Little 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 the schema already documents each parameter, giving a baseline of 3. The description adds genuine meaning on top: what 'keep' means for surviving prompts/renders and staleness, and what keep_image preserves when converting a clip back to an image.

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

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

Opens with a specific verb+resource scoped to a single segment, then names and defines its three sub-actions (combine, change_type, rewrite). An agent can distinguish it from sibling segment_edit or render 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 routes across alternatives: exact text goes to segment_edit set_prompts, clips/talking heads come from render action=animate, overlay text goes to editor_edit scene_note, and renumbering requires re-reading the storyboard. It also states the when-to-confirm condition ('only after the user saw which').

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=false, idempotentHint=false and destructiveHint=false, so the safety profile is covered structurally. The description adds one behavioral fact, that settings apply to the next run rather than retroactively, but says nothing about what is overwritten, whether existing settings must be preserved, or auth requirements. Value beyond annotations is minimal.

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?

It is a single short sentence with no padding, which is structurally fine, but the brevity comes at the cost of under-specification rather than efficiency. Nothing is front-loaded beyond a restatement 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?

For a mutation tool with no output schema, the description should at minimum explain the write and its effect on downstream storyboard generation. It gestures at the run dependency but leaves the operation, overwrite behavior, and relationship to storyboard_generate/storyboard_read unexplained, which is too thin for a 3-parameter required-schema edit 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 description coverage is 100%, so action, sfx_level and project_id are each documented at the schema level, including the enum meanings for sfx_level. The description adds no parameter semantics at all, so the baseline 3 for fully covered schemas 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 'Storyboard settings, used by the next storyboard run' restates the title rather than stating an action verb, so it never says what the tool actually does (edit/set). The clause about the next storyboard run is the only added information, and it describes effect timing rather than the operation. Without the name and title, an agent could not tell this mutates settings.

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

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

There is no explicit when-to-use guidance and no named alternatives, though the sibling storyboard_generate and storyboard_read exist and are the natural contrast points. The phrase 'used by the next storyboard run' weakly implies invocation prior to generation, but nothing states when not to use it or how it relates to the read/generate siblings.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description earns credit by specifying exactly what is destroyed ('Running it again replaces the whole plan, edits included') and disclosing cost/latency ('The longest step (several minutes)') that annotations cannot express. This is behaviorally richer than the structured hints.

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

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

Front-loaded with the verb and the plan's contents, then moves to prerequisites, behavior, and runtime. It is dense and slightly run-on with stacked parentheticals ('(its timing drives the cuts)', '(several minutes)'), but every clause carries information rather than 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?

Covers the prerequisite, the conditional media behavior, the destructive re-run semantics, and the monitoring loop, which is substantial for a four-parameter mutation with no output schema. It does not describe the shape of the returned plan, which is the main remaining gap for an agent consuming the result.

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 project_id, model, settings, and editable_sections. The description adds no syntax or format details for any parameter (e.g. nothing on how editable_sections maps to the mentioned [SCENE: ...] directions), so baseline 3 applies.

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

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

States a specific verb and resource ('Plan the storyboard') and enumerates the exact artifacts produced: segments, timing, image and motion prompts, overlays, continuations. It also distinguishes itself from the edit/read siblings by noting that clips come later and that re-running replaces the plan, so an agent can separate it from storyboard_edit, render, and storyboard_read without opening a 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?

Gives a concrete prerequisite ('Needs the finished voiceover (its timing drives the cuts)') and conditional scope ('real photos and B-roll when the director style has the @real-media tag'), plus a monitoring instruction ('get_status wait=true, repeatedly'). No sibling tool is named as an alternative, so it stops short of explicit when-not 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 already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, and the description adds real cross-tool context beyond them: earlier_renders means 'what a rollback can restore' and public_url is 'for view_image'. Those hints link returned data to segment_edit rollback and view_image usage, though return size/paging behavior is only implied.

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

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

Two dense definition-style blocks keyed by the two action values, front-loaded with 'segments:' and 'segment_assets:' and no filler. It is efficient, but the absence of any lead sentence stating the tool's purpose makes the entry feel like a schema dump.

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 response-shape burden and does so thoroughly for both actions (segment fields, asset fields, statuses, URLs, rollback data). It omits only an explicit purpose/usage statement, so an agent knows what comes back but must infer when to call it.

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

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

Schema coverage is 100%, so every parameter is already documented in the schema; baseline 3 applies. The description adds no parameter syntax or format detail beyond what the schema states (e.g. segment_number as a handle, limit=0 returns all) and instead spends its budget on return fields.

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 never states a purpose sentence; it documents the two returned shapes (segments, segment_assets). Combined with the title 'Read the storyboard' and the action enum, an agent can infer this reads storyboard data, but the description itself never says what the tool does and does not differentiate it from storyboard_edit or segment_edit.

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

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

There is no when-to-use or when-not-to-use guidance and no alternative named. The only routing information (segments vs segment_assets, paging via limit/offset) lives in the schema's action/limit descriptions, not the description text.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is known. The description adds real substance on top: exactly what each action replaces (fields' text, the reference list), that four fields plus script_prompt cannot be removed, that analysis silently rewrites art/narrative/director/text styles, and that update_references sets inputs_stale=true. It stops short of permissions/auth scope and what happens when a style already exists on create.

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?

Front-loads the purpose and then segments cleanly by action label (create/update_fields/update_references), with dense, low-waste prose. A few asides such as 'offer the user two real options, never invented ones' read as instruction padding, but nothing is redundant enough to hurt.

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

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

For a complex, destructive, multi-action tool with no output schema, the description covers workflow ordering, field-level constraints, tag conventions, and the app-only limitation for file references. Remaining gaps are error/edge behavior (creating over an existing style, validation failures) and what the call returns.

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 3-baseline is met by default; the description goes beyond it by explaining conventions the schema does not: contributes_to ['art_style'] for look-only references, presets being one-per-axis, the literal @real-media tag in director_style, and that references must be the COMPLETE list in order copied verbatim from style_read. This is meaningful added semantic content, not restatement.

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

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

The opening line gives a specific verb+resource with scope: 'Create or change the channel style (one per channel, used by all its projects)'. The three action branches then differentiate this tool from siblings by offloading reads to style_read (action=presets) and template images to style_generate (action=template), so an agent never confuses it with those 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?

Explicit when/when-not is given per action: 'Presets and references don't mix', 'never invented ones', 'update_fields ... never starts an analysis', 'File references can only be added in the app'. It also names the prerequisite workflow (wait via get_status wait=true, then style_generate action=template) and the alternative read tool for source data.

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 safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds genuinely useful behavior on top: an existing template is refused unless replace=true, and replacing it 'changes the look of everything rendered after'. That downstream-impact warning is exactly the kind of context annotations cannot convey. It does not describe the analyze mutation's reversibility or scope, keeping it below 5.

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

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

Every sentence carries information, but the structure is cramped notes-style prose with awkward line breaks and no leading sentence stating the tool's overall purpose. The reader must reconstruct the two-action model from the body rather than getting it front-loaded, which is a genuine structural gap rather than mere length.

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

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

For a 7-parameter, two-action tool with no output schema and no destructive annotations, the description covers the action semantics, ordering constraints, and the template-replacement consequence well. The remaining parameters (model, settings, editable_sections) are only covered by schema text, and there is no explanation of what analyze returns, but nothing critical to 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 semantics the terse enum descriptions do not: it spells out what 'analyze' actually rewrites (art_style, narrative_style, director_style, text_style, 'replacing hand edits') and ties 'replace' to the user's intent ('true only when the user asked for a new image'). That is meaningful meaning beyond the schema labels.

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 two specific actions and their effects: 'analyze' rewrites the four style fields, and 'template' renders one of the style's two template images. That is a concrete verb+resource statement an agent can act on. It never distinguishes itself from siblings like style_edit or style_read, so it stops short of 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?

Real sequencing guidance is given: finish both template images 'before any reference image', and run template once per type ('run once for each' appears in the schema). It also states the refusal condition and the replace escape hatch. It offers no routing guidance relative to style_edit/style_read alternatives, so it is clear context rather than full when/when-not 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 already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: null vs URL semantics for templates with the implication that re-rendering is wasteful, staleness flags that drive follow-up actions, and the fact that script_prompt is long and only returned on request.

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?

It is dense but nearly every clause carries information (field list, template semantics, staleness behavior, preset contents), and the primary action is front-loaded. The colon-fragmented, typo-laden formatting ('the summary analysis wrote for each') makes it harder to scan than it needs to be.

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, so the description carries the full return-value burden, and it does so thoroughly for both actions: what each style field is, how templates are represented, what the stale flags mean, and what the preset catalog contains per axis. An agent has everything needed to call it and act on the result.

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 real meaning: channel_id and project_id are interchangeable for the get action, and include_script_prompt is characterized as pulling a 'long' field 'on request', telling the agent to avoid it by default. The presets action is also explained rather than left to the enum alone.

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 and opening state a specific verb+resource ('read the channel style'), and the description enumerates exactly what is returned per action (references, style fields, summaries, templates) plus preset catalog contents. It also implicitly separates itself from siblings by pointing to style_generate action=analyze and view_image as distinct operations rather than doing those things itself.

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 conditional routing for follow-ups: offer style_generate action=analyze when inputs_stale, offer to re-render when templates_stale, and view_image instead of re-rendering when a template URL exists. It does not explicitly say when to choose style_read over style_edit or when not to call it, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior. The description adds 'inline' display behavior and accepted image categories, while the schema adds host restriction. These are useful behavioral details 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?

A single front-loaded sentence with no wasted words. It efficiently states the action and gives examples of accepted image types.

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 one-parameter viewer with safety annotations, the description plus schema are nearly complete. 'Show inline' conveys the return behavior in the absence of an output schema, and the schema covers host refusal, though more detail on output format could help.

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

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

With 100% schema description coverage, the single URL parameter is already well documented in the schema, including the host restriction. The description's enumeration of image categories overlaps with the schema and adds only slight 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?

States a specific verb ('Show') and resource ('Framesail image inline'), and enumerates image categories (segment, reference, style template, preset preview). It does not explicitly differentiate itself from sibling read tools, but the purpose is clear.

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 viewing images sourced from read tools, and the schema states that other hosts are refused. However, it gives no explicit when-to-use/when-not guidance and does not name alternatives among the many sibling tools.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false; the description adds cost information ('free'), a prerequisite for set_voice, and specific non-destructive behavior for rescan_blocks ('assets untouched; blocks whose words are unchanged keep their audio'). It does not cover error modes or what happens to blocks whose words did change.

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-loads the action breakdown. The opening phrase 'Voices and voice blocks; free.' is slightly cryptic, but overall it uses space efficiently without unnecessary repetition.

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

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

For a multi-action edit tool with no output schema and rich parameter descriptions, the description covers the three actions, prerequisites, and key behavioral effects. A small gap remains around rescan_blocks consequences when block words change, but the core call context 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 description coverage is 100%, so the schema already documents all six parameters and the action enum in detail. The description adds prerequisite and action context but little parameter-specific meaning beyond what the schema provides, which is the baseline-3 case.

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 enumerates three specific actions (set_voice, rescan_blocks, settings) on the voices/voice-blocks resource, making the tool's scope clear. It does not explicitly name or route against sibling tools like voiceover_read or voiceover_generate, so sibling differentiation rests on the title and schema rather than the description itself.

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 usage context for each action: set_voice is needed before a voiceover ('every speaker needs one before the voiceover'), rescan_blocks applies after an edit, and settings controls engine and speed. It stops short of naming alternative tools or stating when not to use the tool.

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

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

Annotations only cover the safety profile (write, open-world, non-idempotent, non-destructive); the description adds substantial behavior beyond them: required dependency ordering, the skip of already-generating blocks, the constraint that the model must match the project's voice engine, and the side effect that an existing storyboard retimes automatically.

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 short sentences, the core action front-loaded, and each clause carries a distinct constraint (prerequisites, default scope, model rule, retiming). Slightly terse/fragmented phrasing ('and every asset a reference image') costs a little readability but not 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 six-parameter mutation tool with no output schema, the description covers prerequisites, default behavior, the model constraint, and the storyboard side effect. It leaves out failure modes (e.g. missing voice/reference image handling) and what a successful run returns, but annotations and the dry_run parameter cover most of the remaining ground.

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, but the description adds value the schema lacks: the re-generation semantics of voice_block_ids ('again if they have audio' vs 'omit for every block without audio') and the hard constraint that the chosen model must match the project's voice engine.

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

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

The opening 'Generate voice block audio' gives a specific verb plus resource, and the surrounding constraints (blocks, speakers, reference images, retiming) make clear this is the audio synthesis step rather than a settings edit. It does not name the sibling it should not be confused with (voiceover_edit / voiceover_read), so it stops short of full differentiation.

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 real prerequisites ('Every speaker needs a voice first, and every asset a reference image') and the selection condition for voice_block_ids ('without ... it fills every block with no audio'). No explicit when-not or named alternative is given, so the agent must still infer that voiceover_edit handles post-generation changes.

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

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

With readOnly, idempotent, non-destructive and closed-world hints already declared, the description adds genuinely new context: it spells out the two return shapes in the absence of an output schema, notes that `[SCENE: ...]` directions are 'never spoken', and exposes all_complete/reference-timing fields. It stops short of covering pagination or error behavior.

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

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

Two tightly keyed clauses, 'voices:' and 'blocks:', are front-loaded with the action names so an agent can scan the right one immediately. The brace/field notation is compact and slightly telegraphic but wastes no sentences.

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

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

For a read tool with no output schema, the description usefully enumerates both result shapes and flags the non-spoken scene directions. The main gap is that it never states the project_id requirement for the blocks action or anything about size/limits, but otherwise it covers what an agent needs.

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 input schema already documents every parameter, including the group filter ('large ElevenLabs catalog') and the bulky word-level timings flag. The description adds only marginal meaning (voice_id = the speaker's voice) and does not clarify that project_id is needed for the blocks action.

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 precisely what each of the two read actions yields: voices returns {groups, voices} for an engine, and blocks returns {blocks, total_duration_ms, all_complete}. That is a specific resource description tied to the action enum, though it never names a sibling (e.g. voiceover_edit / voiceover_generate) to differentiate the read path.

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?

There is no explicit when-to-use or when-not guidance and no mention of alternative tools. Usage is only implied by the action enum and its schema descriptions, so an agent can infer that 'voices' is for catalog lookup and 'blocks' for project data, but the description itself does no routing.

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