Vixdeo — Tu Productor IA

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

Goes well beyond the annotations (destructiveHint=true, idempotentHint=true) by disclosing that the change applies directly to the Studio version without committing a draft, that the next final render picks it up, that a delivered final triggers a NEW paid render the line won't start itself, the `deliveredFinal` response flag, the `write` requirement, and $0 cost.

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 action and packs high-value constraints (clip rules, render implications, cost) into dense sentences. Slightly long with nested parentheticals, but nearly every clause carries operational value.

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

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

For a destructive, no-output-schema mutation tool, the description covers effect model, delivery/paid-render consequences, the response flag, auth, and cost — everything an agent needs to call it correctly and warn the user.

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

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

Adds real meaning beyond the 60%-covered schema: `scene_index` is 0-based like the VBP, and the `clip` object is explained ({start_sec, duration_sec|end_sec}, ≥2 s, images take no clip). The `shows` and `asset_id` params rely on schema text, so it isn't fully compensating but does clarify the trickiest nested parameter.

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

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

States a precise verb+resource (put a library asset as the visual of ONE scene) and anchors it to a known human workflow («Mi Media»), making scope unambiguous. An agent can tell this apart from list_material or list_versions 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 clear context for when to use it (assigning a specific asset to a single scene, video vs image handling, requires `write`). It does not name sibling alternatives (e.g., list_material to discover assets first), so it stops just short of explicit when-not/alternatives guidance.

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

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

The description goes well beyond the annotations: it documents the 60 s wait window with measured hit rate, both outcome shapes (completed_inline vs still_running with runId), the 15-minute dedup window that makes retries free, request_id as an explicit repeat key, and the per-project concurrency limit. It also states the required write scope and that LLM budget is spent, which the destructive/idempotent hints do not convey.

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

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

The core behavior, timing, and dedup semantics are front-loaded and the op list is scannable. It is dense and occasionally repetitive (the retry/dedup idea is stated twice), but nearly every clause carries operational meaning.

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

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

For a mutation tool with no output schema, the description supplies the return contract, timing behavior, idempotency story, concurrency constraint, and auth/budget requirements. An agent has everything needed to call it and interpret the response.

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

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

With schema coverage at 50%, the description compensates by spelling out each op's args (scene_index, brief) and clarifying that brief re-authors the WHOLE scene, while request_id's 24 h key semantics are stated in both places. Only the nested args object remains loosely specified.

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 gives a specific verb and resource: runs one authoring edit op that re-authors with the LLM and stages the result into the conversation draft. It enumerates the supported ops with their targets (rewrite_scene, tighten_hook), so purpose is unambiguous. It stops short of differentiating itself from near-siblings like run_op, stage_op, or rewrite_script, which are never named.

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 through the op list and the note that only one authoring turn runs at a time per project, plus the write-scope and budget caveats. There is no explicit when-to-use-this-vs-alternatives guidance despite several plausible siblings (run_op, stage_op, rewrite_script, direct).

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, idempotentHint), disclosing honest limits: an in-flight worker may finish its step and artifacts are kept/reused, money already spent is spent, nothing is deleted, and production resumes later. Also declares the write-auth requirement and $0 cost — rich behavioral context an agent needs before invoking.

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 spends each subsequent clause on a distinct, load-bearing fact (side effects, limits, idempotency, auth, cost). No filler; every sentence earns its place.

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

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

For a mutation tool with no output schema, the description carries the full burden and does so: it explains what changes, what survives, reversibility/resumption, idempotency, and auth. 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 only 50% (project_id has no description), and the description never explains either parameter. It implies project scoping via 'a project's production', but adds no syntax or meaning beyond the names, leaving the undocumented project_id to inference.

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 (stops) and resource (a project's production), then enumerates the concrete effects: line moves drive → manual, live runs (script, build, final render) are marked cancelled. An agent knows exactly what this tool does without opening any schema.

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

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

Usage is implied by the semantics (halt an in-flight production), but the description never states when to reach for this vs. doing nothing or using a sibling like get_project_status, nor any preconditions beyond requires-write. Adequate but no explicit 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 only cover safety hints (writes, non-idempotent, non-destructive), so the description carries the important behavioral load: it re-validates coherence with the same blocking/non-blocking report the human sees, force overrides a blocking report, and the operation requires `write` scope and is `$0`. These are substantive traits 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?

A single dense sentence that front-loads the core action and the resulting state, then appends the two option behaviors and cost/auth facts. No filler and each clause earns its place.

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

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

For a mutation tool with no output schema, the description covers the state transition (`isHead: true` in the answer), the gating behavior, the branch alternative, the required scope, and cost. 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 67% – force and as_branch already have descriptions – but the description sharpens them with concrete semantics ('overrides a blocking report', 'keeps the new version as a branch ... where it can become the cut later'). project_id remains undocumented in both places, keeping it from 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 ('commits') and resource ('staged conversation draft as a new version') and clarifies the resulting state ('makes it THE CUT the production line renders'). The agent can distinguish this from siblings like set_head or cancel without opening any schema.

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

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

Clearly signals the precondition (a staged draft) and the two behavioral modes (force to override a blocking gate, as_branch to keep it as a branch instead of the cut). It stops short of explicitly naming when to use set_head instead, so routing against siblings is implied rather than spelled out.

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

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

Goes well beyond the annotations: it discloses that no provider is involved, the exact verification criteria (in storage, declared size, real media), content-based dedup ('the same file twice is one asset'), the measurement of kind/size/duration, and the meaning of each `stage` value including `failed` with `reason`. The idempotency note ('the same request repeated later returns its current stage') is consistent with 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?

Front-loaded with the core action and reasonably dense, but the stage enumeration and verification rules arrive as one long block rather than being structured, which makes it slightly heavy to scan. Nearly every clause earns its place.

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

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

With no output schema, the description carries the full burden and does so: it documents the returned `stage` lifecycle (`uploading`/`verifying`/`ready`/`failed`), the `assetId`, and the `reason` field. An agent has everything needed to call it and interpret the result.

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

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

Schema coverage is already 100%, but the description still adds meaning: it explains that `declared_content` is WHAT the material shows (with a ≤240-char limit and the purpose of scene placement), that `uploads` yields one outcome per item in order, and the handle/ticket relationship. It adds real value on top of the schema.

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

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

The description states a specific verb and resource: it confirms finished uploads and registers them in the creator's personal library, with a clear single-vs-batch scope. It is easy to distinguish from write-side siblings like request_upload or commit, though it never names an alternative to sharpen the contrast.

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: it 'confirms that uploads finished', so an agent infers it comes after an upload, and the note that a repeated request returns the current stage gives useful polling context. However, there is no explicit when-to-use vs. sibling guidance and no stated prerequisites.

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

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

Annotations only give a coarse safety profile (non-read-only, destructive, non-idempotent, closed-world); the description far exceeds that by disclosing the 60 s wait and the outcome branches (completed_inline vs still_running with runId), retry deduplication (same job within 15 min, request_id for deliberate repeats), the one-turn-at-a-time lock, and budget charging including the none_applied exemption. This is exactly the behavioral context annotations cannot convey.

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

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

Front-loaded with purpose and scope before dropping into timing, outcomes and budget detail; every sentence carries information. It is dense and long for a single paragraph, which costs a point, but there is little pure filler.

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

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

With no output schema, the description carries the return contract itself (reply, staged ops, coherence report, both outcome values, runId) and the state model (draft becomes a version on commit). Combined with the schema and annotations, an agent has everything needed to call it, wait for it, and interpret the result.

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

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

Schema coverage is 80% and the schema already documents message, quality, request_id and active_scene_index. The description adds real meaning beyond the schema for request_id (names a deliberately repeated request, interacts with the 15-minute dedup window) and quality (spends LLM budget), though it does not explicitly explain active_scene_index. Slightly above the 3 baseline because the request_id semantics are genuinely enriched.

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+mechanism: a natural-language instruction is read by a 'planner' that picks ops (rewrite_scene / set_scene_fields / ...) and applies them to the staged draft. It explicitly distinguishes itself from siblings that handle 'a single exact op', so an agent can tell it apart from run_op/stage_op 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?

It names the situation this tool is for (an editorial change spanning several fields or scenes, with a concrete example) and points to alternatives for the opposite case ('a single exact op has its own tools'). Prerequisites (requires write, one authoring turn at a time) are also stated.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial behavioral context beyond them: ambiguous handles come back as handle:null and are exposed via `ambiguousHandles`, id is the key while handle is only a label, org-owned entries carry fewer attributes because they may be real people, and the call is $0. This is exactly the kind of disclosure the annotations cannot 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 purpose is front-loaded, but it is delivered as a single dense run-on paragraph with nested parentheses that is hard to scan. Content is largely relevant, but the structure would benefit from breaking out return shape, references, and filters.

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 the return shape, and it does: per-item attributes by source, id/handle semantics, the ambiguousHandles edge case, and the scope field. For a four-optional-param listing tool with clear annotations, nothing the agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents q, limit, gender and language. The description restates the filters ('language (BCP-47 prefix), gender and q filter the catalogue') but adds little syntax or semantics beyond the schema, and never mentions the `limit` parameter. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('lists voices and presenters/faces that can be named in a piece right now') and immediately scopes what comes back: the organization's own plus the platform catalogue. An agent can distinguish this from list_material, list_referents or list_projects 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?

Usage is implied rather than stated: the entries are 'how a piece names its voice or presenter at creation', which tells the agent the context of use. However, there is no explicit when-to-use/when-not guidance, no prerequisites, and no alternative sibling named for a similar listing task.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower. The description still adds real context beyond them: 'Nothing is written', the '$0' cost, and the semantics of in-progress/refused uploads with their stage and reason. It does not cover pagination or freshness ordering beyond 'limit', 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?

Information-dense and front-loaded: return fields come first, then parameter roles, then the write/cost disclaimer. No wasted sentences, though the em-dash-heavy packing makes it slightly dense to parse.

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

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

With no output schema, the description usefully enumerates the returned fields (assetId, size, duration, usage count, upload stage/reason), covering the return contract. Cost and no-write behavior are stated, making it largely complete for a 4-param read tool, missing only ordering/pagination specifics.

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

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

Schema coverage is 100%, so the baseline is 3. The description restates each parameter's effect (kind keeps one kind, asset_id adds the content hash, handle returns upload state), which marginally reinforces the schema but adds little that isn't already documented there.

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 resource (the creator's own material in the personal library) and enumerates exactly what is returned — assetId, kind, filename, declarations, size, duration, usage count — plus the uploads section. It is clearly distinct from list_cast/list_ops/list_projects, though it never names a sibling to route against, so it falls 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?

It implicitly tells the agent which parameter to use for which goal (kind filters by type, asset_id fetches one file with hash, handle fetches one upload state), which is useful routing. But there is no explicit when-to-use/when-not-to-use guidance or named alternative, leaving usage to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context: exactly what is returned, what `compact` prunes (parameter schemas and notes), what `locale` changes, and the cost hint "$0". It stops short of describing ordering/pagination, but for a read-only listing tool this is solid added value.

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

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

Dense but front-loaded: the core resource is named first, then return contents, then parameter behaviors. Some parenthetical nesting and backtick-heavy phrasing add friction, but nearly every clause conveys a distinct fact and nothing is redundant filler.

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

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

With no output schema, the description correctly carries the burden of describing the return payload, enumerating the fields an agent will receive, including the `invocableVia` mapping that ties ops to callable tools. Completeness is good; only the absence of ordering/pagination and of an explicit hand-off to run_op keeps it from a 5.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further than the schema by explaining the practical effect of `compact` (drops heavy, rarely-needed parts while keeping ids, names, one-line meanings) and clarifying the `locale` default and Spanish mirror fields.

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

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

The description states a specific resource and scope: the unified op vocabulary of a project conversation (creation, transition, edition), and enumerates the return fields (name, lifecycle phase, summary, invocableVia, parameter schema, visualTypes). It is clearly distinct from mutating siblings like run_op/author_op, though it never names those siblings to make the contrast explicit.

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

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

Usage is implied (discover the op grammar and which tool runs each op) but there is no explicit when-to-use or when-not-to-use statement, nor any routing to siblings such as run_op. The only conditional guidance is about `compact`, which is a parameter concern rather than a tool-selection 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavioral context: results are ordered by most recent update, archived projects are omitted by design, and the call is free ("$0"). It still doesn't state pagination behavior beyond the schema's limit, which keeps it from a 5.

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

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

Compact and front-loaded: purpose and returned fields come first, then filtering, then the archived exclusion, then cost. The parenthetical asides ("the answer glosses", the trailing "$0.") add some noise and awkwardness but no sentence is truly 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 read-only list tool with annotations carrying the safety profile and no output schema, the description supplies fields, ordering, filters, default exclusions, and cost. Only minor gaps remain, such as result-size/pagination behavior when the limit is exceeded.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds value the schema lacks: concrete example status values (EDITORIAL_BLOCKED, STUDIO_READY, FINAL_REVIEW, PUBLISHED) for a parameter with no enum defined, plus a scope note (100+ projects). The phrasing "one of the `statuses` the answer glosses" is circular, but the examples compensate.

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 (list the caller's organization's projects) and enumerates returned fields plus default ordering, which is more than a bare restatement. It does not explicitly contrast itself with sibling readers like get_project_status or list_versions, but 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?

Filter behavior for `status` and `q` is described, and the caller learns archived projects are excluded by design, which implies when results are relevant. However, there is no explicit guidance on when to prefer this tool over siblings such as get_project_status or list_cast, so usage 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral context: it is '$0', and it precisely discloses what `compact=true` omits and how null defaults are represented, going beyond the annotation profile.

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

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

It is front-loaded with the core definition, and every clause carries information, but it is delivered as one dense run-on sentence packing output-structure details together. It would be more scannable if split into short points; the length is on the heavy side.

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 describing return values and does so thoroughly: it lists the referent fields, explains the null/platformDefaults semantics, names the additional catalogues (duration profiles, output formats, budget tiers, writingProfiles), and covers cost and both parameters. An agent has enough to call and interpret it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's parameter content ('locale selects the language', 'compact=true leaves out...') largely restates what the schema already documents, adding only marginal specificity about which catalogues drop out.

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

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

States a specific verb (list) and resource (creative referents / formats a piece can be produced in) and defines the concept precisely with examples (documentary, explainer, viral short). It also explains the referent id's role ('the value of creative_referent when a piece is created or priced') and enumerates the additional catalogues returned, making it distinguishable from sibling list_* tools.

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

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

Usage is implied rather than stated: the note that the referent id is used when a piece is 'created or priced' and that 'production accepts' these duration/format/budget values hints at the workflow, but there is no explicit 'call this before produce/estimate' instruction or named alternative. No when-not guidance is given.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real behavioral context beyond them: ordering (newest first), the meaning of each status, and the important non-obvious fact that 'superseded' and 'discarded' versions are kept in history and can be re-promoted. It also flags ordering as fixed. Missing only pagination/response-shape behavior, which is defensible given no output schema.

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

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

Front-loaded with the core statement, then the status vocabulary delivered as a scannable definition list. It is long, but with no output schema the field/status enumeration earns its space; the trailing '$0' is a slightly cryptic appendage.

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 carries the return-field burden and explains the domain-specific status vocabulary thoroughly. Gaps remain around the required project_id and pagination behavior across the limit, but the semantic coverage is strong for a list tool.

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

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

Schema coverage is only 50%: 'limit' is documented in the schema but 'project_id' has no description anywhere. The description enumerates return fields (id, number, sequence, parent, origin...) rather than explaining the inputs, so it does not compensate for the undocumented required parameter.

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

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

States a specific verb+resource ('The project's version timeline ... with lineage') and enumerates exactly what is returned. In a sibling set crowded with list_* tools (list_projects, list_ops, list_cast, list_material, list_referents), it unambiguously stakes out the version/lineage domain.

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

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

No statement of when to call this versus siblings like get_project_status, set_head, or get_project_vbp — all of which touch the same version/cut concept. The 'isHead' and status semantics imply a use case (finding the current cut), but the agent must infer it; no prerequisites or exclusions are given.

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

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

Annotations only declare destructive/non-idempotent/non-readOnly; the description goes well beyond them by disclosing the `write` permission requirement, budget/quota consumption and the daily free-action cap, and the exact response signals (`dispatched`, `dispatch.reason`, `line`, `finalRender`) including the no-op behavior when a final is already delivered. This is the kind of cost and side-effect context an agent needs before calling.

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 action and scope, then layers the edge cases; every sentence carries information (permissions, spend, response fields). It is dense and heavily parenthesized with backticks and guillemets, which costs some readability but not accuracy.

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 still names the meaningful response fields and their conditional presence (finalRender only when a final exists, finalRender.quote, dispatch.reason), and covers auth, cost, and idempotency-adjacent behavior. Nothing an agent needs to call this 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 only 50% (project_id is undocumented), but the description compensates by fully explaining confirm_spend's semantics: default false quotes only, true launches a paid render equivalent to «produce again». project_id's meaning is left to inference, but it is self-evident from the purpose.

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 ('starts or resumes the production line of an EXISTING project') and pins down scope: the same sequence as the human «produce» button (enrich → studio build → final render), with publishing explicitly excluded. An agent can distinguish this from run_op/direct/stage_op by the described end-to-end pipeline and the existing-project constraint.

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 when-to-use conditions ('a project created without auto-production once edited' and 'a line that stopped') and a when-not ('Publishing is not part of it'), plus the special case for already-delivered finals. It stops short of naming an alternative sibling tool for the cases it does not cover, so it is clear context rather than full routing.

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

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

With only generic annotations (non-read-only, non-idempotent, non-destructive), the description carries real behavioral weight: signed-PUT mechanics, resumable parts that continue after interruption, expiresAt/partsExpireAt windows, and the crucial clarification that a 403 on an expired part is an expired URL rather than a failed upload and can be re-signed for free. Quota/maxBytes and refusal reporting are also 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?

Purpose is front-loaded and every sentence carries information, but it is delivered as one very dense paragraph with heavy nested parentheses and long em-dash clauses, which costs some scannability for a description of this size.

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

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

There is no output schema, so the description must convey returns, and it does: ticket upload as a signed PUT or a list of parts, part expiry fields, handle-based re-signing, quota and maxBytes, and accepted content types. Nothing an agent needs to invoke and follow through correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema: it explains that handle alone resumes and returns arrived/missing parts, that a refused batch file carries its reason without aborting the rest, that the declared size is part of the signature, and how resumable changes the part layout.

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: it issues upload tickets for the creator's own material and enumerates the three supported forms (single file, batch, resume-by-handle). It never names or distinguishes itself from the closest sibling, complete_upload, so an agent must infer the relationship from the flow described.

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

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

Clearly explains which form to use in which situation (filename+size for one file, files for a batch, handle alone to resume) and states that bytes travel outside the tool. It stops short of explicit when-not-to-use or naming alternatives such as complete_upload.

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 substantial context beyond annotations: asynchronous execution with a run id, how to poll completion, the result version id location, that as_branch=false makes the result the actual cut the line renders, permission requirement, and that it spends LLM budget priced by the piece's writing profile. This goes well past the readOnly/destructive/idempotent hints.

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

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

Front-loads the core action and is dense with useful detail, but the run-id/result-path sentence and nested parentheticals make it heavier than necessary. Every sentence does carry information, so it is dense rather than padded.

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

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

No output schema exists, yet the description explains the return contract (run id, job.result.editorialVersionId, latestRunByKind.editorial_rewrite) plus side effects and cost. Nothing an agent needs to invoke and track this job 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 already 80%, but the description still adds meaning: as_branch=false is framed as "THE CUT the line renders, as committing a draft does," and confirm_spend is tied to the requiresSpendConfirmation flag in the format catalogue. brief/version_id semantics remain largely in-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+resource (rewrites the whole piece under a brief) and immediately scopes it against the sibling that handles a single scene ("a single scene has its own re-authoring op"). An agent can distinguish rewrite_script from author_op/run_op 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?

Explicitly says when to use it (a brief spanning the piece, e.g. act-level rhythm changes) versus when not (single scene → its own re-authoring op). It also gives the operational conditions: async, poll status by run_id, confirm_spend when the writer requires it, requires `write`.

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

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

Annotations already flag destructive=true and idempotent=false, and the description adds substantial context beyond them: it requires the `write` scope, distinguishes $0 deterministic ops from LLM-charged authoring ops (billed like a chat turn), and notes that null deletes fields and that lists replace while nested dicts merge. It does not state reversibility of destructive ops, but the cost/scope/validation disclosure is well above 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 deprecation notice is front-loaded and the per-op bullet list is dense but earns its space, since each op has distinct args and cost behavior. The only real waste is the closing sentence, which repeats the '$0 for deterministic ops' fact a third time after it is already stated inside every bullet.

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 no-output-schema tool with nested args, the description is nearly sufficient: it explains routing, return behavior ('answers what that tool answers, plus a `deprecated` notice'), scope, cost, and per-op args. The remaining gap is that the successor tool names are not surfaced, forcing a `list_ops` lookup during a deprecation window.

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%, but the description compensates by documenting each enum value of `op` and the exact argument shape for every one (order=[int...], scene_index/brief, partial scene objects, voice_spec semantic-attribute caveat, etc.), far beyond the schema's 'see description' pointer for args. Only `project_id` is left implicitly understood, and it helpfully clarifies that swap_voice takes semantic attributes and NOT a voice id.

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 exactly what the tool is: a deprecated alias that routes each edit op to the split tool that now owns it, and it enumerates all seven ops with their semantics. It distinguishes itself from siblings by declaring its deprecation and its routing role, but it never names the two replacement tools directly (it defers to `invocableVia` in the op catalogue), so the agent must take an extra step to find the successor.

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: DEPRECATED since 2026-09-27, kept until at least 2026-10-27, because ops were split by cost between two tools. The implied guidance is 'prefer the split tools', but the alternatives are only referenced indirectly through the op catalogue rather than named, so the when-to-use-this-vs-that decision is not fully closed.

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

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

Annotations cover only the safety profile (idempotent, non-destructive, not read-only). The description goes well beyond that: it explains the state transition (previous cut marked `superseded` and retained in history, not deleted), the downstream effect (next production run renders the new cut), the write-scope requirement, and the cost ($0). That is exactly the extra context annotations cannot supply.

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

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

Three tight clauses, front-loaded with the core verb and resource, then the human-analogue, then the consequences, auth and cost. Nothing is redundant; every clause carries distinct 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 two-parameter mutation with no output schema and annotations already declaring idempotency and non-destructiveness, the description supplies the important missing pieces: reversibility semantics, downstream render effect, and auth/cost. The only shortfall is parameter-level detail for project_id, which is a minor gap against an otherwise complete picture.

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 50% schema description coverage, the description must compensate for the undocumented parameter, but it adds no parameter-level detail at all. project_id is neither explained nor qualified (scope, format, where it comes from), and version_id is only loosely implied by 'an existing version'. The schema does at least describe version_id as belonging to the project timeline, so this is not a total void, but the compensation the coverage gap calls for is absent.

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 an existing version THE CUT the production line renders' — and disambiguates it from neighbouring tools by naming the concrete state it sets (the rendered head), not a vague 'update'. An agent can distinguish this from produce, list_versions, or commit without opening the schema.

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

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

It anchors the operation to a familiar human action ('the same act as the human's «restore» on the version timeline'), which tells the agent when this is the right tool. It also states the 'Requires `write`' precondition and $0 cost. It stops short of naming an explicit alternative or exclusion, so it is clear context rather than 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?

Beyond the annotations it discloses that the op is deterministic and $0, that the draft becomes a new version only when committed, that a hasBlocking draft can still be committed with force=true, and that a concurrent authoring turn leaves the draft untouched (authoring-in-progress). It also states the required write scope. This is substantial behavioral context that the annotations (which merely mark non-readOnly, non-destructive, non-idempotent) do not convey.

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

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

The purpose and boundary are front-loaded before the op catalogue, and every op line earns its place by naming args and cost. It is dense and repeats 'Deterministic, $0' five times, which is redundant, but the length is defensible given five ops with nested arguments.

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 five-op tool with nested args and no output schema, the description covers purpose, per-op arg semantics, cost, scope, concurrency behavior, and the shape of the result (the coherence report with hasBlocking). Nothing an agent needs to invoke it correctly appears to be missing.

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

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

Schema description coverage is only 33%, so the description carries the burden and does so thoroughly: each enum value is documented with its own arg shape (e.g. order=[int...] for replan_scenes, scene_index/fields for set_scene_fields, voice_spec semantic attributes for swap_voice). It specifies merge/delete semantics ('nested dicts merge by key, null deletes'), that lists replace, and the critical constraint that voice_spec takes semantic attributes, not a voice id. This adds far more than the raw schema provides.

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

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

The description states a specific verb+resource ('Stages ONE free edit op on a project') and immediately scopes it as deterministic with no provider call, writing into the project's conversation draft. It distinguishes itself from the paid re-authoring ops and creation fields, which 'have their own tools', so an agent can separate it from siblings like author_op or run_op without opening the schema. The op list makes the exact edited surface explicit.

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

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

It clearly delimits when this tool applies: only the five free ops run here, and paid re-authoring / creation fields belong elsewhere. It adds a state condition (the draft is not touched while an authoring turn is in flight) and note that agent and human edits converge on one op-log. It stops short of naming a specific sibling tool for each alternative, deferring to 'invocableVia in the op catalogue', which is slightly indirect.

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, non-destructive, and closed-world behavior. The description adds meaningful context beyond that: it details the credential's scope semantics ('read' reads; 'write' creates, edits and produces), notes that platform operators are not charged to the wallet for production, and states the cost is $0. This economic and authorization context is valuable, though no rate limits or response format details are provided.

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

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

The description is a single, front-loaded sentence that begins with the tool's purpose and then enumerates the returned fields. Every clause appears to earn its place, but the dense run-on list is slightly less structured than an ideally formatted definition.

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 what is returned, and it does so thoroughly: credential kind and scopes, organization details, attributed user, platform-operator charging behavior, wallet balance, offer, legal acceptance, and server version. Annotations cover the safety profile, so no critical context is missing for an agent to invoke and interpret this tool correctly.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain. Per the scoring rubric, zero parameters yields a baseline of 4. The description appropriately does not discuss parameters and focuses on the returned information.

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

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

The description explicitly defines the identity resource: the credential principal, its scopes, organization, attributed user, platform-operator status, wallet balance, offer, legal acceptance, and server version. It is immediately distinguishable from all sibling tools, which cover production operations, materials, scripts, and projects.

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

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

The description never states when to call this tool versus alternatives, nor does it specify any prerequisites or contexts. The only guidance-like information is the cost '$0', which is not usage guidance. Usage is implied by the name 'whoami' but not made explicit.

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