AtriumKit

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

Annotations already flag non-read-only, non-idempotent, non-destructive behavior, and the description adds real context: a hard 40-scene limit, default insert position at the end, the asset-reference syntax for images, and the demos:read/demos:write scopes required. It doesn't say what happens when the limit is hit or how errors surface.

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

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

Three short sentences, front-loaded with the action and mechanism, then constraints, then auth. Every sentence carries information an agent needs; nothing 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 mutation tool with no output schema and low schema coverage, the description covers the critical semantics and limits. The remaining gap is the meaning of label/intent/narration (e.g., whether narration auto-generates audio), which an agent may have to infer.

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

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

Schema coverage is only 38%, yet the description compensates for the highest-risk parameters: block's provenance, values as a variable map with the 'asset:<key>' convention for images, and position's default of end. label, intent, narration and durationMs remain undocumented beyond their names.

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?

A specific verb and resource ('adds a scene') plus the mechanism ('from a motion-kit block') and scope ('up to 40 scenes'). It also names the sibling that supplies block ids (list_video_blocks), so an agent can act without guessing where the block value comes from.

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 clear preconditions: fetch a block via list_video_blocks first, and note the 40-scene ceiling and required scopes. It stops short of stating when to use update_scene/write_scene/move_scene instead, so the choice among scene-mutating siblings is left implicit.

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 a non-readOnly, non-idempotent, non-destructive write, and the description adds real context beyond them: editor defaults fill unset fields, a tip inherits the preceding step's screen unless overridden, and both demos:read and demos:write scopes are required. It stops short of describing failure modes or what is returned, but nothing contradicts the annotations.

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

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

Front-loaded with the verb and resource, and the permissions requirement is isolated in its own short paragraph. The first sentence is parenthetical-heavy and slightly run-on, but every clause (kind list, placement, defaults) carries information an agent needs.

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 nested-object mutation with no output schema, the description covers kinds, placement, defaults, screen inheritance and authorization. The notable gap is that it never says what comes back — presumably the new step id, which callers need for a follow-up update_step or move_step.

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?

At 64% schema coverage the description usefully adds meaning: it explains the six `kind` values in prose, defines `after` semantics including the "start" sentinel, explains the screen inheritance rule for `screenId`, and clarifies that `fields` is a catch-all for any other step field. It does not explain `place`, `body`, `title` or `ctaUrl` beyond what the schema already says, so it adds value without fully closing the gap.

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

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

Starts with a specific verb+resource ("Adds a step to a guided demo") and then enumerates every step kind the tool can create, so the agent knows exactly what will be produced. The sibling set contains add_scene, update_step and move_step, and this definition is unambiguously the step-creation one.

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 concrete placement semantics (append by default, insert after `after` or at "start", always before a final outro) and states when to pass `screenId` versus relying on inheritance. It never names alternatives such as update_step or add_scene, so it is clear context without explicit exclusions.

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

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

Annotations already declare idempotent=true, destructive=false, readOnly=false, so the safety profile is covered; the description adds beyond that by spelling out the idempotency behavior in human terms ("Adding a demo that is already in it changes nothing"), the viewer-visibility consequence of demo state, and required scopes demos:read/demos:write. It still omits return value and error behavior (e.g., out-of-range position), 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?

Two short paragraphs, front-loaded with the core action and ordering semantics, then the permission requirement. Every clause carries information an agent would otherwise have to guess.

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

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

For a 5-parameter mutation with rich annotations but no output schema, the description covers ordering, overrides, idempotency, visibility, and auth scopes. The only gaps are error/edge behavior (invalid position, non-existent collection) and whether anything is returned, which are minor for this tool's complexity.

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

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

Schema coverage is only 40%, with title, position, and description undocumented in the schema; the description compensates by explaining that position is 0-based and that title/description are per-collection overrides of the demo's own values. Bounds, max lengths, and id patterns come from the schema, and the description adds no syntax guidance beyond that, so 4 rather than 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?

States a specific verb and resource ("Adds a demo to a collection's list") plus the exact insertion semantics (end of list or 0-based position). No sibling does this, and the sentence reads unambiguously as a collection-membership mutation rather than a demo/scene/step 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?

The description makes clear you must already know a collectionId and demoId (with list_collections/list_demos implied as the source) and warns that only live demos are visible to viewers, which shapes when this is worth doing. It stops short of naming an alternative tool or stating when not to use it, so it is strong context without explicit exclusions.

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

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

Annotations only declare non-read-only, non-idempotent, non-destructive. The description adds real behavioral context beyond that: the URL carries only an opaque code (?p=…) and values are stored as workspace data, unknown variables are silently dropped, plan requirements, and the required scopes demos:read/demos:write.

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 core action, then layered detail (mechanism, limit, privacy, plan, return values, scopes) with no filler sentences. The standalone 'Requires:' line makes the permission requirement easy to scan.

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

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

No output schema exists, and the description still states what comes back ('each link's hosted URL and embed URL'). With both parameters accounted for and annotations covering the safety profile, an agent has everything needed to call this 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 50%, and the description compensates well for the 'values' parameter by listing the built-in keys (first_name, last_name, full_name, company, title, email) and noting custom ones come from content.variables, plus the 500-item cap and the drop-unknown-keys rule. The 'label' field is left entirely 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?

States a specific verb and resource ('Makes personalized links for a demo, one per prospect') and immediately explains the mechanism — per-link variable values substituted into the demo. It is unmistakably distinct from the read-side sibling list_personalized_links.

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

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

Provides concrete usage context: bulk creation 'Up to 500 at once, e.g. from a CRM list', plus plan gating (Pro and Team only). It does not name an alternative tool or state when not to use it, so it stops short of the top score.

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 write/idempotency/open-world profile, and the description adds two things beyond them: the required scopes (demos:read, demos:write) and the fact that the result starts with exactly one title scene. It stops short of saying what is returned (e.g., the new video id) that an agent needs to chain into add_scene.

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

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

Two sentences and a requirements line, front-loaded with the defining trait (blank, one title scene) before the alternative. No filler; every clause carries information.

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

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

For a non-destructive creation tool with no output schema, the description covers intent, alternatives, and auth, but omits the three input parameters entirely and says nothing about the return value an agent must use to continue building the video. Adequate to choose the tool, insufficient to call it confidently.

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 0% for all three parameters (title, aspect, themeId), so the description carries the full burden — yet it mentions none of them. 'One title scene' faintly hints that a title exists, but nothing explains aspect ratios, theme selection, or defaults, leaving an agent to infer from bare property names and an enum.

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 is produced — a blank video containing one title scene — and how it is meant to be used (built by hand with add_scene). The verb 'create' lives only in the name/title, so the description itself is a sentence fragment, but the resource and scope are unambiguous and clearly separable from generate_video.

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 an explicit alternative with its selection condition: 'To make a video from a demo or a brief, use generate_video,' and names the follow-on tool for the manual path (add_scene). Both the when and the when-not are stated outright.

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 and idempotentHint=true, so the safety profile is partly covered. The description adds genuinely new context: the required scopes (demos:read, demos:write) and the fact that deletion is recoverable via two distinct undo mechanisms – neither of which the annotations convey.

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

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

Two short sentences: the action and scope first, then the recovery path and required permissions. No filler, and the most decision-relevant information is front-loaded.

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

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

For a two-parameter, fully documented, annotation-covered delete with no output schema, the description supplies the missing pieces: auth scopes and reversibility. It does not mention side effects such as scene reordering or what happens to steps attached to the scene, which would be useful for a destructive 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%, with both videoId and sceneId documented including format examples and provenance ('from get_video', 'from list_videos'). The description adds no parameter meaning of its own, so the schema-driven baseline of 3 applies.

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

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

States a specific verb and resource ('Removes a scene from the video'), so the agent knows exactly what is deleted and from where. It does not explicitly distinguish itself from sibling mutations like delete_step or move_scene, but the resource noun makes the target unambiguous.

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

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

The description gives a recovery hint (studio undo or chat's Undo), which implies this is a destructive action to be used deliberately, but it never states when to choose this over delete_step, update_scene, or other scene operations. Usage is implied rather than guided.

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=true, idempotentHint=true) by explaining exactly what happens to referencing objects: choices and 'next' links are rewired to the deleted step's own target, or cleared/unlinked when it had no next. It also discloses that revision history preserves the previous version, restorable from the dashboard's History, which is precisely the context an agent needs before a destructive call.

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 action, then the side effects, then the recovery path and permissions; every sentence carries information. The first sentence is dense and parenthetical-heavy, but nothing is wasted or redundant.

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 two-parameter mutation with no output schema, the description closes the key gaps: what is destroyed, how references are rewired, whether the change is recoverable (revision history), and what scopes are required. Nothing an agent needs to invoke it safely 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 50%: demoId carries a description with an example and provenance (from list_demos), while stepId has only a pattern constraint. The description says 'one step from a guided demo's draft', which implicitly maps the two parameters but adds no format, sourcing, or validation detail 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?

Specific verb+resource: 'Removes one step from a guided demo's draft' clearly separates it from delete_scene and from add_step/update_step by naming the object type and the draft scope. It stops short of explicitly naming a sibling as an alternative, so it is clear but not fully differentiated.

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

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

Usage is implied by the consequence narrative (removal relinks choices and next links), and the required scopes (demos:read, demos:write) are stated. However there is no explicit when-to-use / when-not guidance versus update_step, move_step, or delete_scene, so the agent must infer that this is the tool for permanently removing a step.

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

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

Adds real context beyond the annotations: what gets copied, that the output is a *draft* rather than a published demo, and the required scopes demos:read/demos:write. It implicitly explains the non-idempotent hint (each call makes another copy) but does not state the source is left untouched or what the response contains.

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

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

Two sentences of behavior plus a permission line; the core copy semantics are front-loaded and nothing is padding. The name_format detail is compactly embedded rather than belabored.

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-input, non-destructive duplicate operation with full annotation coverage, the description covers inputs, permissions, and resulting state. The only gap is not saying what the call returns (e.g. the new demo's id), which matters because there is no output schema.

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

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

Only one parameter and the schema already documents it fully with a pattern and an example value sourced from list_demos. The description adds no further meaning about demoId, 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 (copies) and resource (a demo) and enumerates exactly what is carried over — screens, content, settings, translations — plus the resulting artifact being a new draft. This clearly distinguishes it from update_demo, translate_demo, or stitch_demo.

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?

"Useful for a variant per audience" gives a motivating scenario, which is more than nothing, but there are no explicit when-to-use/when-not conditions and no routing to alternatives such as translate_demo or stitch_demo for related-but-different jobs.

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?

Exceptional disclosure beyond the annotations: job semantics (1-3 minutes), 20-second synchronous wait, credit cost (5/10, refunded on failure), plan gating, and the narration-retention nuance for walkthroughs vs other formats. All consistent with the non-idempotent, non-destructive write 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?

Front-loaded with "Beta" and the core action, then layers cost, timing, and preconditions. Dense but every sentence carries operational information; the run-on quality of the first sentence slightly hurts scannability.

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 contract well: it either returns the finished video or its progress state. Also covers plan/permission gates and credit spend. Only minor gaps remain around what the progress payload contains.

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

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

Schema covers 73% of parameters, and the description adds real meaning on top: what proof means (never invented, so omit it and none is shown), how narration behaves per format, and that look can be omitted to let the director choose. A few parameters (title, aspect, lengthSeconds) are covered only by schema.

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

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

States a specific verb and resource: an AI director makes a motion video from a brief and/or demos, with a described pipeline (storyboard of 10-15 beats, gathers screens/b-roll/music, designs scenes, records narration). This clearly distinguishes it from read-side siblings like get_video, though it never explicitly contrasts with create_video, which is the most likely point of confusion.

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

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

Gives an explicit follow-up rule: if the job is still "generating" after the 20-second wait, call get_video rather than generating again. It also states prerequisites (demos:read/write, verified email on Free plan). It stops short of explaining when to prefer this over create_video.

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 mutation profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, closed-world), so the description only needs to add context — and it does, with required scopes (demos:read, demos:write) and the practical warning that scene durations should fit the narration. It doesn't cover whether existing audio is preserved or how long generation takes, which leaves some behavioral gaps.

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

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

Two tight sentences plus a scoping line — front-loaded with the action and its filter, then prerequisites. Minor density in 'Uses AI voice characters; scene durations should fit the narration (get_video shows them)' but every clause carries information.

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

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

For a 2-parameter mutation tool with no output schema, the description covers scope, prerequisites, and one important pre-condition. What's missing is the return/latency story — whether generation is synchronous and what comes back — which an agent needs before invoking a media-generation operation.

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

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

Schema coverage is 50%: videoId is documented in the schema but sceneIds has no description. The phrase '(default: all of them)' explains exactly what omitting sceneIds does, compensating for the undocumented optional parameter. It still doesn't mention the 40-item cap or ordering, so it falls short of 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?

States a specific verb and resource ('Records AI narration for scenes') plus a clear scope condition ('whose script has no current audio'). It does not, however, distinguish itself from the near-identical sibling 'generate_voiceovers', so an agent comparing the two gets no disambiguating signal.

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 scope rule (only scenes lacking audio, defaulting to all of them) and the pointer to get_video for checking scene durations imply when this tool is appropriate. But there is no explicit exclusion or alternative-selection guidance, which matters given the sibling generate_voiceovers looks like a direct substitute.

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 destructiveHint=true and idempotentHint=false already declared, the description still adds substantial context the annotations cannot: AI credits consumed, monthly narration-character quota with graceful stop-and-report, drafts saved before generation, unchanged clips skipped, and identical inputs reusing earlier clips for free. That is exactly the cost/side-effect/partial-failure information an agent needs before spending quota.

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 outcome, then parameter effects, then cost/publish consequences — a logical order with no filler sentences. It is a dense single paragraph that runs long and packs several ideas per clause, which slightly hurts scanability.

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, nested-object, quota-consuming mutation with no output schema, the description covers permissions, cost, partial-completion behavior, and the downstream publish step. The only gap is the shape of the result ('reports what was done' is vague) and error behavior when a target id is invalid.

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

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

Schema coverage is 100%, so the schema already documents all six parameters and the baseline would be 3. The description still adds sequencing semantics the schema lacks: `scripts` is persisted to the draft first, `writeMissing` burns 1 AI credit per 20, and `voice` is drawn from list_voices.

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: 'Gives a demo spoken narration' per step (guided) or screen (clickable), with captions — an agent knows exactly what artifact is produced. It does not, however, distinguish itself from the sibling generate_video_voiceovers, so the reader must infer the demo-vs-video split from the name alone.

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

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

Explains the workflow clearly: pass `scripts` to set copy, `writeMissing` to draft with AI, optionally `voice`, then clips are made only where missing or stale. It also carves out an exclusion ('Translations' narration is generated in the editor') and points to publish_demo for going live. No explicit routing against generate_video_voiceovers, which keeps it from 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 read-only, idempotent, non-destructive behavior, but the description adds substantial context beyond them: required scopes, UTC/today-inclusive time semantics, free-plan view-only behavior, and different drop-off semantics for linear vs branched demos. These details materially affect interpretation of results.

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

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

The description is dense but front-loads the primary metrics and then explains demo-level and branched behavior. It is appropriately sized for the complexity, though long sentences make it slightly harder to scan than a bulleted structure would 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?

With no output schema and a complex, context-dependent response, the description explains what is returned in each mode, including funnel steps, drop-off behavior, traffic sources, paths, and plan limitations. Required permissions are also stated, leaving little an agent needs before calling 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 description coverage is only 50%, but the description compensates well: it explains that days defaults to 30, includes today, uses UTC, and that demoId switches the entire response shape from workspace totals to per-demo funnel, path, and session analytics. This adds meaning well beyond the schema.

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

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

The description names the exact metrics returned (views, unique visitors, completion rate, average time, leads) and clearly distinguishes workspace-level totals from single-demo analytics. No sibling tool covers analytics, and the scope is unambiguous.

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

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

It clearly states the two usage modes: omit demoId for workspace totals, provide demoId for per-demo funnel and session analytics. It also explains the free-plan limitation, though it does not name alternatives or explicit when-not-to-use conditions, which are less relevant here because no sibling analytics tool exists.

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 still adds real context beyond them — the required 'demos:read' scope, that null values in the kit document are derived, and that `resolved` includes contrast warnings and feeds AI copy. No error/not-found behavior is disclosed.

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

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

Front-loaded with 'One brand kit in full' and then a single dense sentence that maps the return payload; the parenthetical field lists are informative rather than filler. It is long but nearly every clause carries payload semantics.

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 thoroughly — it names the four top-level sections, explains derived nulls and contrast warnings, and states the auth scope. An agent has enough to call it and interpret the result; only not-found behavior is unstated, which is minor.

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

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

Schema coverage is 100% and the single parameter already documents its pattern and points to list_brand_kits for discovery. The description adds nothing about themeId beyond what the schema says, 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+resource ('One brand kit in full') and enumerates the four payload sections it returns (settings, kit document, resolved colors, knowledge kit), which is far more specific than the bare name. The read-one vs list-many distinction with list_brand_kits is only implied via the parameter description, not stated in the description text.

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 'use when'/'don't use when' guidance or named alternative; usage is inferred from the required themeId and the description's content inventory. The 'Requires: demos:read' line gives a useful precondition but not selection 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 cover safety (readOnly, idempotent, non-destructive), and the description adds genuinely non-obvious context beyond them: the 'demos:read' scope requirement, that `revision` is a concurrency token for update_content, that unknown newer fields are preserved as-is, and that the server validates the whole document. What's missing is any note on payload size or whether large demos are truncated.

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 summary is well front-loaded, but the body then expands into a multi-hundred-word prose re-specification of the entire content document (camera options, branching target types, personalization tokens, voiceover clip internals). Nearly all of that is field-level schema detail that belongs in the write tools' schemas, not in a read tool's description; the reader must wade through it to reach the one operational note (revision → update_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?

There is no output schema, so the description legitimately must describe the return shape, and it does so thoroughly across guided steps, clickable hotspots, share/publish fields and the revision token. It is short only on what 'share settings' actually contain, but an agent has enough to call the tool and use 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?

There is a single parameter with 100% schema description coverage (including a pattern and an example), so the schema carries the semantics. The description adds nothing about `demoId` itself — no hint that it comes from list_demos or how to handle an unknown id — which matches the baseline for a fully-documented 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 sentence names a specific resource and enumerates its scope precisely: content document, screens, share settings, published state, hosted URL, embed code, and revision. It also explicitly names the sibling get_screen for the narrower screen-level case, so an agent can distinguish the two without opening either 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?

Usage is implied rather than stated: the 'pass it to update_content' note and 'Look at a screen with get_screen' route the agent to two related tools, but there is no explicit 'use this when you need X instead of list_demos' framing. The agent must infer that this is the inspect-before-mutate call.

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

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

Annotations already cover the safe-read profile (readOnly, idempotent, non-destructive), and the description adds real context beyond them: the required scope 'demos:read', the hard prerequisite that the demo be published, the exclusion of draft changes/presenter notes/private sources, and locale fallback to source language. It stops short of describing failure behavior when the demo is unpublished or the locale is unsupported.

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 return payload, then locale, then plan/prerequisite/permission — a sensible ordering with no filler sentences. The single long sentence with stacked parentheticals is dense and could be split for faster scanning, but every clause carries information.

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

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

With no output schema, the description carries the full burden of explaining return values and does so concretely (Markdown body, step pictures, outline structure with ids/numbers/titles/URLs/branching). Permissions, plan scope, prerequisite and locale behavior are all covered, so an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds one genuinely new fact the schema lacks: the locale parameter defaults to the demo's source language. It also restates that only published languages are accepted, which the schema already says, so the gain is modest rather than comprehensive.

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 (a published demo rendered as a step-by-step guide) and precisely defines the output: Markdown plus per-step pictures plus an outline of sections/items with step ids, numbers, titles, picture URLs and branching choices. The phrase 'exactly as viewers get it (the published version: no draft changes, presenter notes or private sources)' implicitly separates it from get_demo, which serves the editable draft view.

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 names the prerequisite tool explicitly ('the demo must be published (publish_demo)') and states plan availability ('Every plan'), plus the locale fallback rule. What it does not do is explicitly route the agent to get_demo for the draft/editorial view, so the alternative is only implied rather than named.

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 read-only, idempotent, non-destructive safety profile, but the description adds real behavioral context: redaction (hidden, blurred and personal data never appears), a 1568 px scaling cap, and the required `demos:read` scope. It stops short of describing pagination or response envelope, 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?

Front-loaded with what the agent gets, then the outline/units detail, then a terse scope requirement. Dense but every sentence carries information; only minor tightening is possible.

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

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

With no output schema, the description carries the full burden and discharges it: it enumerates return fields, coordinate units, HTML-only outline behavior, redaction guarantees, and auth requirements. An agent can call this correctly without further inference.

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

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

Schema description coverage is 100% and the schema already documents both `demoId` (from list_demos) and `screenId` (from get_demo → screens) with patterns. The description adds no further parameter semantics, 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 precisely characterizes the payload: a screenshot (blurred/edited, capped at 1568 px), readable text with positions, and an `outline` of elements for HTML screens. That is enough to tell it apart from get_demo (metadata/screen list), though the phrasing is a noun phrase about output rather than an explicit verb+resource statement.

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?

Use is implied rather than stated: it explains that rects share units with a tooltip step's `spot` and a hotspot's `rect`, hinting at the 'point a step at an element' use case. There is no explicit when-to-use/when-not or a named alternative among the many siblings (get_demo, get_guide, get_video).

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 behavior. The description adds useful context beyond annotations: the required demos:read scope, the presence of a generation status field, and the cost/use of includeHtml. It does not describe error behavior, but it substantially enriches the behavioral picture.

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

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

The description is dense and largely front-loaded with the return shape, then the generation status and includeHtml guidance. It has no filler, though it is a single long paragraph where bullets or slight restructuring could improve scanability.

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 burden of explaining the return value, and it does so in detail: scene fields, narration status, editable variables, generation progress, and optional HTML. Combined with the permission requirement, this is complete enough for correct invocation.

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

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

Schema coverage is only 50%, so the description must compensate for includeHtml, which it does thoroughly by explaining its purpose and when to use it. videoId is already well documented in the schema with an example and pattern. The description meaningfully adds to the parameter semantics.

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

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

The description clearly identifies this as retrieving a video and details what the returned video contains (look, voice, music, captions, ordered scenes, generation status). It distinguishes scene-editing siblings by pointing to update_scene and write_scene, but it does not explicitly contrast with get_demo or list_videos.

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

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

It gives explicit guidance for includeHtml: use it only for hand-editing a scene via update_scene html, and use write_scene to change how a scene looks or moves. It does not state when to choose get_video over get_demo or list_videos, but the main conditional usage is covered.

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, idempotentHint, destructiveHint=false, openWorldHint=false), so the description's added value is the 'Requires: demos:read' scope, which is an authorization detail not present in any structured field. It also defines the two return values semantically, which is genuinely useful for a tool with no output schema.

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

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

Two short sentences, front-loaded with what the agent gets back and followed by the permission requirement. No filler and nothing buried.

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 parameterless read with no output schema, the description carries the necessary burden by describing both returned values and the required scope. Minor gaps remain, such as whether the allowance resets on a calendar month or a billing cycle, but nothing blocking.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a 0-param tool is 4. No misleading parameter talk is introduced.

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 exact quantity returned: remaining exported-video seconds for the month plus whether exports carry the 'Made with AtriumKit' watermark. That is specific and clearly distinct from the mutation siblings (generate_video, create_video) and from get_analytics. It stops short of naming the sibling it complements, so it is a clean 4 rather than 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?

There is no explicit when-to-use statement or named alternative; the agent must infer that this is a pre-flight check before calling generate_video or create_video. The phrase 'left this month' implies the quota-checking use case but nothing in the text says so.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description adds substantial extra context: the auth requirement (`demos:read`), plan-based editability (Pro: one kit, Team: up to 20; Free can only rename), and the fact that the default kit is used by new demos and videos. It stops short of describing pagination or rate limits, but for a zero-parameter read tool this is strong disclosure.

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 one long, dense sentence that packs the field list, plan constraints, and themeId usage into a single run-on, followed by a short auth note. It is front-loaded with the resource and avoids repetition, but it could be split or structured more cleanly for readability. Every element is relevant, yet the presentation is less scannable than ideal.

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 and no parameters, the description carries the full burden of explaining return values and context. It lists the returned fields (id, name, default status, colors, fonts, brand name, logo, header button, knowledge kit flag), explains editability semantics, states the auth requirement, and ties the themeId to update_demo. That is complete enough for an agent to call the tool correctly.

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

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

The tool takes no parameters, so there is no parameter semantics to explain. Schema description coverage is 100% for the empty object, and the baseline score for zero parameters is 4. The description correctly spends no space on parameters.

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 (workspace brand kits) and enumerates the fields returned, making the plural/list nature clear. However, it is a noun phrase rather than a specific verb phrase, and it does not explicitly contrast with the sibling get_brand_kit. The title and name supply the verb, so an agent can infer the operation, but the description itself could be sharper.

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

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

The description implies usage by explaining that `editable` reflects plan limits and that a demo picks its kit via `update_demo { themeId }`, giving useful context for why one would inspect kits. But it never says explicitly when to use this tool versus `get_brand_kit` or other alternatives, and it offers no exclusions or preconditions beyond the auth requirement.

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 adds value beyond that by declaring the auth scope (demos:read) and enumerating the fields the caller will receive, which is meaningful disclosure for a tool with no output schema. It does not mention result limits or pagination 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 short sentences: the payload specification first, then the hard prerequisite. There is no filler, and the inline gloss on 'demo centers' resolves an ambiguous domain term in a single clause rather than a paragraph.

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 correctly steps in and lists the returned fields, including ordering for demo ids, so an agent knows what it gets back. The main remaining gap is any statement about result size, ordering of collections, or pagination, which matters for a workspace-level listing.

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

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

The tool takes zero parameters, so there is nothing the description needs to disambiguate; the baseline for zero-param tools applies. The description instead spends its words on the response shape, which is a reasonable use of the space.

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 precisely (the workspace's collections) and even defines the domain term 'demo centers' so the agent knows what a collection contains. It stops short of naming a verb or distinguishing this list from nearby list tools such as list_demos or list_brand_kits, but the identity of the resource is unambiguous.

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

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

'Requires: demos:read' gives a concrete permission prerequisite, which is genuinely useful for gating a call. However, there is no guidance on when to reach for this versus list_demos or how it pairs with add_to_collection, so the agent must infer its place in the toolset.

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 value beyond that: sort order (most recently updated first), which fields appear and that the hosted URL is only present when live, and the required `demos:read` scope — an auth requirement annotations cannot express.

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 blocks with zero waste: the first front-loads purpose, ordering and return shape, the second covers filtering/pagination, and the trailing line gives the scope requirement. Nothing is repeated from the schema verbatim except where clarification is needed.

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 by enumerating fields (id, title, type, status, counts, views, URL). Filters, pagination, ordering and the required permission are all present, so an agent can call this correctly without further inference.

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

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

Schema coverage is only 50%, and the description compensates well: it defines the type enum (guided = tooltip walkthrough, clickable = hotspot sandbox), restates status as draft/live, and maps query, folder and cursor to their filtering/pagination roles. Only `limit` is left unaddressed in both schema and description.

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

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

States a specific verb and resource ("Lists the workspace's interactive demos") and enumerates the returned fields, so the agent knows exactly what kind of data comes back. It does not explicitly name or contrast with a sibling (e.g. get_demo for a single demo), but the listing scope plus "interactive demos" separates it from list_videos and similar siblings.

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

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

"Filter by title search, folder, status or type. Paginate with `cursor`." gives clear guidance on how to narrow and page results, and the ordering (most recently updated first) is stated. It stops short of explicit when-not-to-use or pointing to alternatives such as get_demo for a single record.

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 read-only, idempotent, non-destructive, closed-world, so the description rightly spends its words elsewhere: ordering, pagination behavior, required scopes ('demos:read, leads:read'), and a personal-data handling constraint. It stops short of describing return shape details or empty-result behavior, but the added context is well beyond what annotations provide.

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

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

Front-loaded with the entity definition, then filtering, then pagination, then the privacy constraint and scopes — a logical order with no filler. The field enumeration in the opening sentence is long but earns its place given there is no output schema.

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 returned fields (compensating for the absent output schema), ordering, both filtering paths, pagination, required permissions, and a PII usage restriction. An agent has everything needed to call it correctly and responsibly.

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 only 25%, so the description must compensate, and it does: `query` semantics (matches email, name, or company) and `demoId` (filter by demo) are clarified beyond their bare property names, and `cursor` is reinforced. Only `limit` is left fully to the schema, where min/max/default already make it self-explanatory.

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 resource (lead-form/email-gate submissions) with scope and ordering ('newest first') and enumerates the returned fields, so an agent can tell it apart from list_demos, list_collections, or get_analytics 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?

Explains how to narrow results ('Search by `query` (email, name or company) or filter by demo') and how to page, but never says when to prefer this over get_analytics or other list_* siblings that expose overlapping entity data. Usage is implied through mechanics rather than stated through selection criteria.

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

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

Annotations already declare a safe, idempotent read; the description goes well beyond them by disclosing the auth model ('Requires: demos:read', 'leads:read') and, critically, the degraded behavior without leads:read (labels render as 'Link <code>' and stored personal data is withheld). It also flags the non-obvious pagination/query interaction, which an agent could not infer from structured fields.

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 resource and return shape, then permissions, then pagination — a sensible order. The field enumeration in sentence one is slightly dense but earns its place since there is no output schema. 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?

With no output schema, the description correctly compensates by listing returned fields, and it covers auth scopes, redaction behavior, and pagination mechanics. Minor gaps remain: no mention of what `limit` bounds mean in practice or what happens on an invalid/expired cursor, but nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 75% and already documents `query`, `cursor`, and `demoId`, so the baseline is 3. The description adds genuine semantics on top: `query` matches only the labels shown on each page and pagination ignores the query entirely, a caveat absent from the schema. `limit` semantics are left to the schema's default/max, which is adequate.

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 first sentence names the resource (personalized links of a demo), the ordering (newest first), and exactly which fields come back, so an agent knows precisely what this returns. It never explicitly contrasts with the one closely related sibling, create_personalized_links, so sibling differentiation is left implicit.

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

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

It gives operational guidance for use (paginate with `cursor`, `query` only matches labels on the current page) and states the required scope. What's missing is tool-selection guidance: nothing tells the agent when to reach for create_personalized_links or list_leads instead, so the 'when vs alternatives' dimension is only 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?

Annotations already cover read-only/idempotent/non-destructive, and the description adds a genuine non-obvious detail — 'Requires: demos:read' — plus the fact that authoring rules for hand-written scene HTML are included in the response. It does not state the response shape or ordering, but with no output schema the enumerated look catalog compensates substantially.

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?

Roughly 250 words for a zero-argument list tool, with six long parenthetical mini-essays describing each look's visual style and target audience. The single most important clause — that this returns the available scenes/looks — is buried in a sentence fragment rather than front-loaded, and the marketing-style scene-setting ('words blurring into focus', 'a drifting light leak') is not what an agent needs to select or invoke the 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?

With no output schema, the description must convey what comes back, and it does enumerate the six looks and mention authoring rules. But it never explains how blocks are identified (name slugs? ids?), what the authoring-rules content actually looks like, or whether scene blocks and looks are separate collections in the response — gaps an agent needs closed to chain into write_scene or update_video.

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

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

The tool takes zero parameters, so the description has no parameter burden to carry; baseline is 4. Nothing in the text misleads about inputs.

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 naming the resource ('ready-made scenes ... and its looks ... plus the authoring rules') but never states the verb — nothing says it lists or returns them, despite the tool name and title both saying 'list'. It does differentiate well from siblings by referencing add_scene, write_scene, and update_video, which is the strongest part of its clarity.

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 concrete relational guidance: add_scene fills a scene block with values, write_scene can start from one, and the looks are presets for update_video — this effectively tells an agent how the returned data is consumed downstream. It stops short of an explicit call-to-action ('call this before write_scene to discover valid looks') and names no when-not-to-use conditions.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real value beyond them: default sort order ('most recently changed first'), the exact set of returned attributes, and the required auth scope. Return format/pagination remains unstated, keeping it at 4.

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 lines with the resource and ordering front-loaded and no filler. The parenthetical definition and the enumerated return fields are informative rather than wasteful, though the field list is slightly list-like padding for a listing 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?

With no output schema, the description supplies the return shape and ordering, and it names the required scope - enough for an agent to call it correctly. Pagination/limits and filtering behaviour are the notable omissions.

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

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

Schema coverage is 100% and the single 'query' parameter is fully documented in the schema, so the schema does the heavy lifting. The description never mentions the title-substring filter, adding nothing beyond structured data - baseline 3.

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

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

States a specific verb+resource ('The workspace's videos') and even characterizes what a video is (AI-directed motion videos made from demos or a brief), plus the returned fields and ordering. It does not explicitly contrast with siblings like list_demos or get_video, 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?

The permission prerequisite 'Requires: demos:read' is useful context, and the plural/list framing implies bulk retrieval. But there is no explicit statement of when to use this versus get_video (single video) or list_demos, leaving the choice to inference from naming.

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 readOnly/idempotent/non-destructive, and the description adds substantial extra context: it discloses the two voice sources, the workspace narration status payload, subscription/trial allowance semantics, the monthly character allowance, and the demos:read auth requirement. It stops short of 5 only because it doesn't state anything about result size or filtering behavior beyond the language parameter.

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 what is returned and keeps the permission note last, which is good ordering. The parenthetical on Pro/Team subscriptions and 'recording and uploading happen in the editor' is slightly digressive but still useful orientation for the caller.

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

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

With no output schema, the description compensates fully by enumerating the voice fields and the workspace narration-status fields, plus the auth scope. For a single-optional-parameter read tool, an agent has everything needed to call and interpret 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% and the lone 'language' parameter is already documented in the schema ('Only default voices plus library voices of this language'). The description adds no additional meaning about that parameter's format or edge cases, 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+resource ('The AI voices narration can use... with id, name, gender, accent, age, language and description') and even enumerates the returned fields. It distinguishes itself from action siblings like generate_voiceovers by positioning this as the lookup that feeds them.

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 final line 'Pass a voice id to generate_voiceovers' gives an explicit downstream-use path, and 'Requires: demos:read' states a prerequisite. It does not enumerate when-not-to-use or name a direct alternative list tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds useful behavioral context beyond annotations: it is scoped to one workspace per connection and requires demos:read, though it does not discuss rate limits or response shape beyond the listed fields.

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

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

The description is compact and front-loaded: it states the returned resource and contents first, then gives the related tool usage and permission requirement. Every sentence contributes useful information.

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

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

For a zero-parameter, read-only tool with no output schema, the description is complete enough: it lists the returned data, clarifies the one-workspace-per-connection scope, gives the required permission, and explains how returned ids are used elsewhere.

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

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

The tool has zero input parameters, so there are no parameter semantics to explain. Baseline for zero parameters is 4.

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

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

The description clearly identifies the resource and scope: the AtriumKit workspace for this connection, including role, plan, credits, folders, and brand kits. It is more specific than a tautology, but it does not explicitly frame itself as a list/get operation or distinguish itself from siblings like list_brand_kits.

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 by explaining that the returned folder and theme ids are used with list_demos and update_demo, and it states the demos:read permission requirement. It does not provide when-not-to-use guidance or compare directly against alternative listing tools.

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

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

Annotations already declare non-read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds the concrete auth requirement (demos:read, demos:write), which is exactly the kind of context annotations cannot express; what it omits is whether other scenes shift and what happens on an out-of-range position.

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

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

Two short sentences, front-loaded with the action and the key positional convention, followed by the permission prerequisite. Nothing is wasted or buried.

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 3-required-param, non-destructive reordering mutation with annotations and no output schema, this covers action, key parameter convention, and auth scopes. An agent has enough to call it correctly; further return-value detail is not needed 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 coverage is 67% – sceneId and videoId are documented, but position has no schema description. The description compensates by explaining that 0 means first, giving meaning the schema does not; the upper bound (max 40) and shifting behavior remain unexplained.

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 ("Moves a scene") plus the destination semantics ("to another position (0 = first)"), which is more than the title alone conveys. It does not differentiate from the closely named sibling move_step or from update_scene, so an agent must infer which one reorders vs. edits.

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 parenthetical about position 0 implies a reordering use case, but the description never states when to use this instead of move_step or update_scene, nor any preconditions beyond the permission scopes. Usage is implied rather than guided.

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 this is non-read-only, idempotent, non-destructive, and closed-world. The description adds useful auth context (demos:read, demos:write), but it does not explain side effects such as how other steps are reordered after a move.

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

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

The description is two short sentences, front-loaded with the core action and positioning modes. The permissions line is compact and no sentence is wasted.

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

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

For a simple move operation with no output schema and reasonable annotations, the description covers the key placement options. It still leaves gaps around exactly one placement parameter being required, stepId meaning, and reordering side effects.

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 low (20%), so the description carries extra burden. It helpfully clarifies that toIndex is 0-based and that after/before refer to another step id, but it leaves stepId semantics and the mutual exclusivity of the placement parameters implicit.

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

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

The description states a specific verb and resource: moving a step within a guided demo. It clearly describes the positioning options (toIndex, after, before) but does not explicitly distinguish this tool from siblings like update_step or move_scene.

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

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

It implies the tool is used when repositioning an existing step and lists the permission requirements. However, it gives no explicit when-to-use guidance versus update_step or move_scene, and no exclusions.

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

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

Annotations flag destructiveHint=true and idempotentHint=false, and the description explains why: publishing replaces what viewers see immediately and produces a new version vN retained in revision history — effectively disclosing reversibility. It also names concrete failure modes with reasons, states required scopes (demos:read, demos:publish), and describes the return payload, which is far beyond what the annotations provide.

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

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

The verb and effect lead; failure conditions, return values, and required scopes follow in descending order of importance. Two short paragraphs, no filler, every clause carries load-bearing information.

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

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

With no output schema, the description supplies the return contract (hosted URL and embed code), plus preconditions, auth scopes, and side effects. For a single-parameter publish operation, nothing an agent needs in order to call it or interpret failure 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% — demoId is documented with a format pattern and a pointer to list_demos — so the schema already carries the parameter burden. The description adds nothing about demoId (e.g., that it must reference a draft rather than an already-published demo), 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?

"Publishes the current draft" is a precise verb+resource statement, and the follow-on sentence describes the exact effect (viewers of the hosted link, embeds and collections see it immediately). This cleanly separates it from sibling mutations like update_demo, duplicate_demo, and unpublish_demo without needing to name them.

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

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

The description gives a clear context for use (current draft → live for viewers) and explains what blocks the call: "no steps, a broken link" or the plan's published-demo limit. It does not explicitly route to a sibling (e.g., unpublish_demo to take a demo down, or update_demo to fix steps first), so it stops just 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 declare destructive=true and idempotent=false, and the description goes well beyond them: changes are saved to the draft, revision history retains the old copy (softening the destructive hint), {{variables}} are never touched, and narration replacement invalidates existing voiceover clips. Required scopes (demos:read, demos:write) are disclosed, which annotations cannot express.

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 action and its scope, then alternatives and modifiers, then requirements — a sensible order. However, it is one very long semicolon-chained sentence that is dense to parse; splitting the scope enumeration from the modifier definitions would read better without losing 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 7-parameter mutation tool with no output schema, it covers the prerequisites (scopes), the side effects (draft save, revision history, narration clips), the preview path, and the exclusions. The dryRun sentence even hints at the return shape (counts and listed locations). Nothing material 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 only 43%, but the description compensates by defining all four undocumented booleans in prose: matchCase (case-insensitive by default), wholeWord (skips matches inside longer words), dryRun (counts and lists only), and includeNarration (plus its downstream consequence). Only find/replace semantics are left implicit, which the opening sentence adequately implies.

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

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

States a specific verb+resource (replace a word/phrase across a demo's copy) and immediately enumerates the exact surfaces covered: guided steps, hotspots, description, personalization defaults, guide overrides, narration. An agent can distinguish this from rewrite_copy, update_content, or update_demo purely from this 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?

Explicitly names the two boundaries: the demo title belongs to update_demo, and on-screen text in screenshots/HTML pages is out of scope (use the editor's Find & replace). It also names the prerequisite follow-up (regenerate voiceovers after narration replacement) and the dryRun preview path, so the agent knows both when to use it and what to do next.

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?

Well beyond the annotations: it discloses the exact blast radius (every scene's text variables including untouched defaults, scene labels, narration scripts, video title), what is explicitly spared (images, colors, asset keys), the downstream consequence that narration audio must be regenerated with generate_video_voiceovers, and the required scopes. That is precisely the context a destructive, idempotent=false mutation needs and annotations alone 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?

One dense but front-loaded block: the verb and scope lead, then the affected surfaces, then the flags, then the exclusions and scopes. Every clause carries information, though the long parenthetical chain of text-variable examples and nested caveats makes it a run-on that is slower to parse 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?

For a 9-parameter destructive mutation with no output schema, the definition covers scope, side effects, defaults, required permissions, and roughly what the response contains (a list of scenes needing rewrite, or counts in dryRun mode). The main residual gap is sceneIds semantics and whether there is any undo path after a save.

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 only 56% schema description coverage, the description carries real weight: it defines matchCase (case-insensitive by default), wholeWord (skips matches inside longer words), dryRun (counts and lists only, saves nothing), and includeNarration with its default. It does not explain the sceneIds parameter, which is a meaningful scoping control for a video-wide mutation and is undocumented in both places.

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 scope — "Replaces a word or phrase across a whole video in one save" — with a concrete renaming example that makes the resource boundary obvious (video-wide, not scene- or demo-wide). It carves out write_scene for the one exclusion case, so an agent can separate it from that sibling. It does not address near-neighbors like replace_in_copy or rewrite_copy, leaving some ambiguity among the 'replace text' family.

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 usage scenario (renaming a company or product everywhere) and an explicit non-fit routing (custom scene markup cannot be replaced here — use write_scene). It also frames dryRun as the preview path. What is missing is an explicit comparison against the sibling replace_in_copy/rewrite_copy tools, which an agent could easily confuse with this one.

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 annotations: the destructive hint is contextualized ("revision history keeps the old copy"), cost is quantified ("1 per 20 strings" of AI credits), required scopes are stated (demos:read, demos:write), and subtle behaviors are disclosed — {{variables}} are preserved, auto-stitched navigation links are untouched unless named, and then only rewritten once per link group.

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 core action and example instruction, then progressively narrower scoping rules. Dense — a long paragraph with nested parentheticals and brace notation — but nearly every clause carries operative information, so little is wasted.

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

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

For a 7-parameter destructive mutation with no output schema, this covers cost, permissions, reversibility and scoping thoroughly. The remaining gap is the return shape when `apply=false` (what a "suggestion" contains and whether it maps to stepIds), which an agent would want before running in review mode.

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 already 86%, yet the description still adds meaning: a concrete `instruction` example ("for a CFO audience, shorter, mention month-end close"), the `apply` default-true behavior with what false yields, and the non-obvious `stepIds` semantics for stitched link groups. It also clarifies `fields` intent for choices ("a card with choices has no button").

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 ("Rewrites a demo's copy with AtriumKit's AI") and anchors it to a known in-product feature ("the same strings as 'Write with AI' in the editor"). It doesn't name the closest sibling (replace_in_copy) to draw the AI-rewrite vs literal-replacement boundary explicitly, so differentiation is inferable rather than stated.

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 clear usage context: it covers all steps or hotspots by default, or can be narrowed via `stepIds`/`fields`, and it explains the two operating modes (apply=true saves, apply=false returns suggestions to review). No explicit when-not or named alternative, 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 read-only, idempotent, non-destructive behavior, and the description adds useful context: plan availability, required permission, indexed source types, and ranked result structure with kind, snippet, and location. It does not cover rate limits or error behavior, but it substantially exceeds the annotation baseline.

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

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

The description is front-loaded with the core purpose and then packs scope, result shape, follow-up tool, plan, and permission into a compact block. Every clause carries useful information, and there is no filler.

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

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

There is no output schema, but the description supplies the return shape by explaining ranked results with kind, snippet, and location. Combined with the annotations, permission requirement, plan restriction, and follow-up guidance, it gives an agent enough context to invoke the tool correctly.

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

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

The query parameter is well documented in the schema with examples, and the description reinforces what content is searched, but the limit parameter has no semantic explanation in either the schema or the description. With 50% schema description coverage, this is adequate but leaves a clear gap around result-count control.

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

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

The description names a specific verb and resource, "Searches the workspace's internal knowledge base," and enumerates the indexed content types and result kinds. It also distinguishes the search action from the follow-up get_guide action, so an agent can tell what this tool does versus its sibling.

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

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

It clearly explains that search results should be opened with get_guide for guides or steps, and it states the Pro/Team plan and demos:read permission requirements. It does not explicitly describe when not to use the tool or name another search alternative, so it falls 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?

Beyond the annotations it discloses required scopes (demos:read, demos:write), that an empty list deletes existing choices (consistent with destructiveHint=true), how rendering differs between cards and tooltips, and that the response reports resulting paths plus problems such as unreachable steps or paths that never end. No contradiction with readOnlyHint=false or openWorldHint=false.

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

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

The fork concept lands in the first sentence with examples, then removal, then the update_step alternative, then the result shape — a sensible front-loaded order. Parentheticals about card vs. tooltip rendering are dense but each carries real behavioral information.

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

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

For a three-parameter mutation with no output schema, the description covers what the tool does, the meaning of the ambiguous `goTo`, the deletion case, the relevant sibling call, the permissions needed, and what comes back in the result. Nothing an agent needs before calling 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 67%, and the description goes beyond the schema on the key semantic point: an omitted `goTo` means the choice is unlinked and viewers fall through to the default path, which no schema field states. It does not add anything for `label` or the choice `id` beyond what the schema already documents, which keeps it below the top mark.

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

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

The description names a specific verb and resource — turning a tooltip or card step into a branching fork with 2–4 choice buttons — and concretely illustrates each choice target (step, end, URL). It is clearly distinguishable from update_step, which is instead invoked for the `next` pointer that rejoins or skips paths.

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 the operational cases directly: omit `goTo` to link a choice later, pass an empty list to remove choices, and use update_step with `next` when the goal is to skip ahead or rejoin rather than fork. That routes the agent to the right sibling for the adjacent task, though it never states a condition under which this tool should not be used at all.

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 by naming required scopes (demos:read, demos:write), stating it never changes or duplicates existing hotspots, and noting the player-side effect (added links are quiet, no pulse) and grouping. It clarifies the mutation lands as one draft change undoable from version history, consistent with destructiveHint=false and idempotentHint=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?

Purpose and the dry-run rule are front-loaded, and the sentences about player behavior and safety are load-bearing. The long first sentence is dense and slightly nested with parentheticals, mildly taxing to parse, but there is no filler.

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

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

No output schema exists, so the description carries the burden of describing returns and does so (links/screens/groups, suggestions with key and why). Combined with permissions, undo semantics, non-destructiveness, and the automatic-linking context, an agent has everything needed to call it safely.

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

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

With 100% schema coverage the baseline is 3, but the description adds real meaning: it explains the dry-run/inspect/apply cycle for apply, that accept takes suggestion keys from a prior apply:false run, and it sketches the response shape (links across screens per control in groups, suggestions each with key and why). It stops short of enumerating the demoId format, which the schema already covers.

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 action (auto-linking navigation controls to the screens they lead to) on a specific resource (a clickable demo's sidebar items, tabs and menu links). The mechanics — matching by link address or by identity with a recorded click — make the effect unambiguous. It does not explicitly differentiate itself from siblings like update_scene or add_step, which keeps it at 4.

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

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

Gives an explicit two-step workflow: run with apply: false first to inspect what it would add and the weaker suggestions, then apply: true optionally with accept keys. It also states when to reach for it: new recordings are linked automatically, so use this for demos recorded before or after adding screens.

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

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

Beyond annotations, the description discloses important side effects and constraints: the language and picker appear only after the next publish_demo, AI credits are consumed at 1 per 50 strings, and the operation requires demos:read and demos:write. This is rich behavioral context for a non-readonly mutation 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?

The description is front-loaded with the main action, then follows with the retranslate behavior, publish timing, plan/cost constraints, and required permissions. Every sentence adds useful information without waste.

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

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

For a mutation tool with no output schema, the description is sufficiently complete: it explains what is changed, when viewers see the result, the cost model, plan restrictions, and required permissions. An agent has enough information to decide whether and how 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%, and both locale and retranslate already have descriptive enums and defaults in the schema. The description adds some context around locale being added if absent and retranslate covering missing/outdated/all, but it largely repeats what the schema documents rather than adding syntax or format details.

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

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

The description uses specific verbs and resources: it adds a language to a demo and translates its copy with AI. It also scopes the operation to missing/outdated strings or all strings, making it distinguishable from sibling copy tools like rewrite_copy or replace_in_copy.

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 clearly states the context: use this when a demo needs a new language and AI translation of copy, with missing/outdated versus all behavior. It also gives prerequisites such as Pro/Team plans and AI credits, but it does not explicitly name an alternative tool or when not to use this one.

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 and idempotentHint=true, but the description adds the crucial nuance the annotation cannot: the draft and its history are preserved, so 'destructive' means only the public surface goes dark. It also discloses required scopes (demos:read, demos:publish), which no structured field conveys.

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

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

Two short sentences: effect first, then preservation/reversal, then permissions. No filler, no restatement of the title, and the most decision-relevant fact (link and embeds go dark) leads.

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 mutation with rich annotations and no output schema, everything an agent needs is present: the visible consequence, what survives, how to undo it, and the auth scopes required. Nothing material 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% and the single demoId parameter is fully documented with a pattern and a source hint (list_demos), so the description adds nothing here. Baseline 3 applies when the schema already 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?

States a specific verb and resource ('takes a demo offline') and immediately defines the observable effect: hosted link and embeds stop showing it. This cleanly separates it from publish_demo and the delete_* siblings, which is exactly what an agent needs to pick correctly.

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

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

It names the reverse operation (publish_demo) and makes clear this is a reversible takedown rather than a deletion, which implicitly routes agents away from delete/destroy options. It does not explicitly state a 'do not use when' case, so it stops just short of full 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 flag destructiveHint=true and idempotentHint=true, and the description earns its keep by disclosing the blast radius — "Every demo that uses the kit renders with the change, published ones included" — which is exactly the cascade an agent must warn about. It adds two side effects not in any structured field: font files are self-hosted on save, and null colors re-derive from accent/contrast.

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 field inventory, and every clause carries information (partial-update rule, cascade warning, plan gating, scopes). It is densely compressed into one paragraph with nested parentheticals, which is efficient but slightly harder to scan than separated prerequisite and effect statements.

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 12-parameter mutation with a nested colors object, no output schema, and a destructive cascade, the description supplies permissions, plan gating, partial-update behavior, null semantics, and downstream render impact. The only omission is the return value, which is acceptable absent an output schema.

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

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

At 75% schema coverage the schema already explains accent, tooltip, radius, themeId, fonts, and ctaLabel. The description still adds real meaning the schema lacks: null color values re-derive from accent and contrast, and headingFont null falls back to the body font. It doesn't cover the remaining nested color keys or makeDefault's const constraint beyond naming it.

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 ("Changes a brand kit") then enumerates the exact editable surfaces: name, accent, colors, tooltip surface, fonts, radius, brand name, header button, default flag. This clearly separates it from get_brand_kit / list_brand_kits in the sibling set, which are read operations on the same resource.

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

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

"Fields you leave out stay" establishes partial-update semantics, and "Pro and Team (Free can only rename)" plus the required scopes tell the agent when the call is even permitted. It stops short of naming a sibling alternative (e.g. create vs. edit, or bulk vs. single-field paths), so there's no explicit when-not guidance.

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

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

Discloses validation rules ('validated like the editor'), revision-history recording, the concurrency guard, and required scopes (demos:read, demos:write). This is rich context beyond the annotations, which already flag destructive/non-idempotent semantics, and nothing contradicts them.

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

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

Front-loads the core save semantics and sibling routing before the reference material, and uses clear section headers. It is very long, but much of the length is the document grammar that the open `content` schema cannot express; still borderline verbose.

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

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

For a tool with nested objects, an opaque document payload, and no output schema, the description supplies the structure and field constraints an agent needs to build valid payloads. Nothing essential for a correct call 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 a baseline of 3 applies; the description earns an extra point by documenting the RFC 6902 patch path syntax, '-' append behavior, and the full content document shape that the opaque `content` object schema leaves undefined. The detailed doc grammar meaningfully exceeds what the schema alone provides.

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

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

States a specific verb + resource (saves a demo's content document to the draft) and explicitly contrasts the two modes (whole `content` vs JSON Patch `ops`). It also distinguishes itself from the single-step siblings (update_step/add_step/delete_step/move_step), so an agent can route correctly without opening schemas.

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

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

Gives explicit when-to-use: whole doc vs ops, when to prefer update_step/add_step, and that set_choices is the easy way for branching, generate_voiceovers for clips. It also instructs passing `revision` read from get_demo to avoid overwriting, which is a concrete conditional for correct invocation.

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

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

Goes well beyond the annotations to explain the staging model: edits are saved to the draft and revision history, title/description/theme only reach viewers on the next publish_demo, while settings and access apply immediately. That immediate-effect-on-access warning is exactly the risk context an agent needs for a destructive-flagged 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?

Three tightly packed sentences, front-loaded with the mutable fields, then publish semantics, then permissions. No filler; the parenthetical clarifications replace what would otherwise be schema lookups.

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 mutation tool with nested settings and no output schema, the definition covers staging behavior, permissions and field meanings well. Minor gap: it does not say whether omitted fields are left untouched or what an omitted/partial update does.

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 57% schema coverage, the description compensates for the undocumented fields: it clarifies that `description` renders under the title on the hosted page, that themeId is a brand kit from list_workspaces, and that access is a share setting. The nested `settings` object and `folderId` are left to the schema, so it is not fully comprehensive.

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 (Changes) and enumerates exactly which demo-level attributes are in scope: title, description, share settings, brand kit, folder, access. That enumeration implicitly separates it from content/scene/step siblings (update_content, update_scene, update_step), so an agent can pick it 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?

Gives concrete prerequisites (demos:read, demos:write, plus demos:publish for `access`) and tells the agent where the themeId comes from (list_workspaces). It does not explicitly name an alternative tool or say when not to use this one, which keeps it below 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?

Goes well beyond the annotations: discloses that the call is free and instant, that 'values' are merged rather than replaced, that 'narration: null' removes the field, that HTML edits cause variables to be re-read from the markup, and the required scopes demos:read/demos:write. These are exactly the mutation side effects an agent needs and that readOnly/idempotent/destructive hints 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?

A single front-loaded sentence opens with the core action and the 'free, instant' property, then enumerates fields in a scannable list, followed by a short action-routing line and a one-line requirements footer. Heavy parenthetical nesting, but no sentence is filler.

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

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

For a 9-parameter mutation tool with no output schema, the definition covers constraints, merge behavior, downstream staleness, prerequisites, and tool routing. An agent has everything needed to invoke it without further discovery calls.

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 only 22% with 9 parameters including a nested transition object, so the description must compensate — and it does, explaining semantics for every meaningful field: value merging and 'asset:<key>' image encoding, duration bounds tied to narration length, null narration removal, HTML size cap and authoring rules from list_video_blocks. This is meaning the schema does not carry.

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 concrete verb and resource ('Changes one scene directly') and enumerates exactly which fields are mutable: values, label, intent, duration, transition, narration, HTML. It also disambiguates from the closest sibling by saying to use write_scene for look/motion changes, so an agent can pick correctly without opening schemas.

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

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

Names the alternative tool and the exact condition that selects it ('To change how a scene looks or moves, ask write_scene instead of writing HTML'), plus a follow-up requirement ('Changing the script makes its narration stale: then call generate_video_voiceovers'). It also tells the agent where to source ids and current values (get_video).

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: it discloses merge semantics for omitted fields, precise null-removal behavior per field (including the 'ctaUrl': null nuance), immutability of `id` and `kind`, variable interpolation in text, and that writes land in the draft with revision history preserving the old version. It also names the required scopes (demos:read, demos:write), which annotations do not carry. The removal semantics are consistent with destructiveHint=true, so there is no contradiction.

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

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

Front-loaded with the verb and resource, and every clause carries real information (patch semantics, null behavior, immutable fields, scopes). It is a dense run-on paragraph with many inline examples, which costs some scannability, but nothing is wasted.

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

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

For a mutation tool with a nested free-form object and no output schema, the description covers everything an agent needs to call it correctly: what is mergeable, what null does, what cannot change, where the write lands, and what permissions are required. Return values are not required here 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?

Although top-level schema coverage is 100%, the critical `changes` parameter is a free-form object with additionalProperties: {}, so the schema provides essentially no structure for it. The description compensates by enumerating editable field families (title, body, spot/place, cta/ctaUrl, next, choices, notes, camera, cursor, spotlight) and defining null semantics per field, which the schema cannot express.

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 — changing fields of one step of a guided demo — and scopes it to a single existing step, which cleanly separates it from add_step, update_scene, move_step, and set_choices. An agent can identify the target entity 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?

The description makes clear this is a patch-style edit of an existing step ('Fields you leave out stay as they are') and that null is the removal path, which implicitly routes removal of choices/notes/camera/etc. here rather than to add/delete siblings. It never explicitly names an alternative (e.g. when to use set_choices instead) or states a prerequisite beyond the scope requirement, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the mutation profile is partly covered. The description adds real value beyond that: the partial-update semantics, the non-obvious side effect that changing the look restyles every scene via shared CSS variables, and the required scopes demos:read and demos:write.

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 compact — three short sentences plus a scope line, with the side-effect warning and permission requirement clearly separated. The opening sentence is a dangling fragment with no verb, which costs a point on structure but not on brevity.

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

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

Given 7 parameters, nested objects, no output schema, and a sibling set full of downstream generators, the definition covers mutation semantics, the restyle side effect and auth. It omits what happens to derived artifacts (e.g., whether voiceovers must be regenerated with generate_video_voiceovers) and any mention of invalid-id or validation failure 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 only 14% (only videoId is documented), so the description must carry the load; it does partially by enumerating the top-level fields and the look sub-fields. It still adds no meaning to nested options such as music.duck, voice.speed, captions.style, or the individual color roles, so the compensation is incomplete.

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 exact video-level attributes that can be changed (title, aspect, look with its preset/colors/fonts/motif/pace/radius sub-fields, captions, voice, music), which is a specific resource+operation. It is grammatically a fragment with no verb, relying on the name/title to supply 'update', but the field inventory still lets an agent distinguish it from scene-level edits like update_scene or replace_video_text.

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?

'Only the fields you send change' clearly communicates partial-update usage, which is genuinely useful guidance. However, there is no explicit when-to-use versus siblings (update_scene, replace_video_text, update_brand_kit) and no guidance on follow-up steps such as regenerating voiceovers after a voice change.

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 past the annotations by disclosing that the scene is validated against authoring rules and auto-fixed before saving, that unspecified attributes are preserved on rewrite, and that each call costs 1 AI credit (refunded on failure). This contradicts nothing in the annotations and adds real invocation 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?

Front-loaded with the core action and the dual-mode distinction, then costs and permissions. It is a dense single paragraph, but nearly every clause carries decision-relevant information; only the permission sentence is fully redundant with structured data.

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 mutating, credit-consuming AI generation tool with no output schema, it covers cost, side effects, validation, and failure behavior. An agent has everything needed to decide and invoke 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 already 100%, so the baseline is 3; the description still adds meaning beyond it by explaining the sceneId branch's preservation behavior, the default insertion position, and the source of valid block values. Concrete instruction examples ('punchier, with the numbers counting up') further clarify intent.

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 ('AI director writes one scene') and cleanly splits the two modes: rewrite when sceneId is present, add when absent. It distinguishes itself from siblings by naming update_scene and list_video_blocks for adjacent needs.

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 the agent: 'For plain copy, timing or narration changes use update_scene instead (free and instant)', and points to list_video_blocks when a kit block is wanted. Both the when-to-use and when-not-to-use cases are covered.

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