Vixdeo — Tu Productor IA

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

Annotations already declare non-read-only, idempotent, non-destructive, but the description adds the concrete idempotency semantics (first acceptance wins, repeats return `already_accepted`), the authorization profile (owner only, `write` required), the consent-revocation failure mode, and the $0 cost. These are behavioral facts an agent cannot infer from 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 core action, then edge cases and auth in descending priority; parentheticals carry error codes and defaults without padding. Every clause contributes a constraint, failure code, or scope fact; the trailing 'Requires `write`. $0.' is terse and load-bearing.

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 covers authorization, idempotency, consent failure, and permission scoping, which is most of what an agent needs. It does not say what the call returns or what visible state change follows acceptance (e.g., whether the asset becomes usable immediately), a small remaining gap.

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

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

Schema coverage is 67%, and the description adds real meaning to `permission_scope` beyond the enum documentation: `piece` is the default and `author` applies only when the link asked for it, plus the consent precondition. `asset_id` is already documented in the schema and `project_id` remains undescribed in both places, which keeps this 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 (accepts a contributed file) and pins down the origin precisely: a file a third party sent through a guest upload link, so the piece can use it. That framing implicitly separates it from owner-upload paths handled by siblings like complete_upload, and the `not_a_contribution` note makes the boundary 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?

Covers when to use it (guest-contributed file for this piece) and when not to: an owner-uploaded file needs none (`not_a_contribution`), a guest who withdrew consent cannot be accepted, and repeat calls are no-ops (`already_accepted`). It also states the actor constraint (only the piece's owner) and the required `write` scope.

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 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?

Goes well beyond the annotations: discloses the `write` scope requirement, the $0 cost, the 29.4 s segment cap with picture, that the audio is cut as-is rather than synthesized, that voice regeneration preserves it, and that refusals are typed with a full list of `extensions.reason` codes and leave state unchanged. This is exactly the extra context the destructiveHint/idempotentHint flags cannot carry.

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 scope before the caveats, and the dense clause chain is mostly justified. The parenthetical refusal-code list is long but genuinely useful; a slightly tighter structure would earn a 5.

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, the description covers the mutation's effect, its undo path, the deferred-production timing, permissions, cost, and every refusal reason with the guarantee that refusals are no-ops. An agent can call this correctly and interpret failures without further documentation.

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%, so the baseline is 3; the description adds meaning beyond it by explaining that `from_sec`/`to_sec` are measured from the recording's start, that `with_picture` binds picture to voice with lip sync and imposes a 29.4 s cap, and that `remove` causes the other arguments to be ignored. The `asset_id` linkage to a material-library `assetId` is implied but not restated in depth.

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 ('Sets a recording ... as the narration of ONE scene') and immediately clarifies the effect ('the scene speaks with that voice, not with a synthetic one'), which distinguishes it from assign_material and from synthetic-voice tools in the sibling list. The capitalized 'ONE' makes the per-scene scope unmistakable.

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

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

Clearly conveys when to use it (attach an existing recording as a scene's voice) and when to undo it ('`remove` returns the scene to the cast voice'), plus the constraint that the voice only materializes in the next production. It never explicitly names a competing sibling (e.g., assign_material) as an alternative, so it falls short of full when/when-not routing.

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

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

Beyond annotations, the description discloses the 60-second wait behavior, the two possible outcomes with runId, the 15-minute deduplication window, the request_id 24-hour behavior, one-authoring-turn-per-project concurrency, and LLM budget spending. These are exactly the behavioral traits an agent needs before invoking a paid, destructive mutation.

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 front-loads the core behavior, waiting semantics, and outcomes before listing ops. It duplicates some request_id details already present in the schema and is somewhat lengthy, but nearly every sentence provides actionable context for a complex 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?

Given the complexity, missing output schema, and nested args, the description is complete enough to call the tool correctly: it explains staged results, commit implications, outcomes, run IDs, retry behavior, concurrency limits, scope, and budget. Nothing critical 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?

The schema's nested args object is only described as 'Op arguments (see description)', but the description compensates by listing each op's arguments and explaining scene_index, brief, and when brief is optional. It also explains request_id semantics beyond the schema, though it does not specify formats for project_id or scene_index.

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 clear verb and resource: it runs one LLM re-authoring edit op and stages the result into the conversation draft. The three supported ops are enumerated with distinct behavior, although sibling tools such as run_op and stage_op are not explicitly named or contrasted.

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 specific conditions for each op, e.g. revestir_como_autor for a still image held too long, rewrite_scene for wholesale scene re-authoring, and tighten_hook for scene 0. It also states the write-scope and budget prerequisites, but does not explicitly say when to choose this tool over sibling tools like run_op or stage_op.

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?

Beyond the annotations it explains exactly what happens: the voice is cut from the recording rather than synthesized, an on-scene presenter face is replaced, and re-selecting the same take is a no-op (matching idempotentHint). It also discloses typed refusal reasons, feature gating (`forbidden`, `no_ofrecido`) and that refusals change nothing — behavior an agent cannot get from `destructiveHint: true` alone.

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 effect is front-loaded in the first sentence and every following clause adds information (idempotency, refusal codes, permissions, cost). It is dense and includes one very long sentence with untranslated error tokens, which slightly taxes readability but carries no filler.

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

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

For a destructive, owner-only mutation with no output schema, the definition covers effect, permissions, idempotency and error taxonomy. The one gap is that it does not explicitly state whether the scene's previously chosen voice is discarded — implied by "gives way to it" but not spelled out for a `destructiveHint: true` 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?

The schema already documents asset_id (one of the scene's takes) and scene_index (0-based), and the description largely restates the 0-based fact. It does add the relational meaning that the asset must be a take belonging to that scene within that project, but `project_id` remains undocumented anywhere. Baseline 3 for 67% coverage with modest added meaning.

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: it makes an already-recorded take "the scene's voice" and states the concrete effect (spoken segment used, picture shown when available). It is clearly distinct from list_takes or assign_narration in substance, though it never names those siblings directly, so the agent must infer the boundary.

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 real usage context: the effect lands "in the next production," only the piece's owner may call it, and it requires `write`. It also states the re-choose case changes nothing. What's missing is an explicit comparison to the other routing tools (assign_narration, assign_material) that an agent might otherwise reach for.

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 destructiveHint/idempotentHint annotations by spelling out the exact blast radius: the link dies immediately, in-flight uploads are cancelled, but already-delivered files remain in the material. It also discloses the auth/scope requirement and the zero-cost property.

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 action and its consequence in one sentence, then tacks on the no-op case, permission requirement, and cost as short declarative clauses. Every clause carries distinct information with no restatement of the title.

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

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

For a two-parameter, non-read-only mutation with no output schema, it covers consequences, idempotency, permissions, and even the shape of the no-op response field. An agent has everything needed to call it safely 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?

channel_id is covered by the schema, and the description adds real meaning by clarifying what happens to the entity behind it. The residual gap is project_id, which the schema leaves undocumented and the description only gestures at obliquely with 'the piece's owner'; with 50% coverage this is a modest gap rather than a fatal one.

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 ('Revokes an upload link of a piece') and immediately describes the effect, which clearly separates it from the inverse operation open_channel. It does not explicitly name that sibling as its counterpart, so an agent must infer the pairing from context.

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

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

Gives concrete preconditions — 'Only the piece's owner' and 'Requires `write`' — plus the when-not case: revoking an already revoked link is a no-op returning `revoked: false`. What is missing is an explicit pointer to open_channel for link creation or to list_channels for discovery.

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?

Beyond annotations, it discloses the full asynchronous lifecycle (`uploading`/`verifying`/`ready`/`failed`), idempotent repeat behavior, the `ficha` enrichment stages, and that registration records a rights declaration under Terms §5.1. This is unusually rich behavioral context and is consistent with `idempotentHint: true`, `readOnlyHint: false`, and `destructiveHint: 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 description is long and dense, but it is front-loaded with purpose and organized by lifecycle stage. Most sentences carry necessary information about the return states and rights declaration, though some parenthetical detail could be trimmed without losing 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?

With no output schema and a complex multi-stage response, the description fully explains the possible return states, the optional `ficha` stages, and the rights declaration record. An agent has everything needed to call the tool and interpret its result.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds genuine meaning by explaining that `declared_content` is the director-facing description (≤240 chars) and that `uploads` returns one outcome per item in order. It does not add much for `speaker`/`speaker_name` beyond the schema, but the added context is meaningful.

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

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

The description opens with a precise verb and resource: 'Confirms that uploads finished and registers them in the creator's personal library.' It distinguishes the single-upload (`handle`) and batch (`uploads`) forms, so an agent can tell exactly what the tool does and how it differs from `request_upload`.

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 trigger condition is clear — use it once uploads have finished, not to initiate them. It also explains that repeating the request is safe and returns the current stage. It doesn't explicitly name alternatives or when-not-to-use cases, but the context is strong enough for correct selection.

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

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

Beyond the annotations, it discloses that translation spends LLM budget (paid by Vixdeo, not the wallet), that the call counts as one daily action, exactly which artifacts are inherited/reused vs re-made, and that the answer carries a typed `outcome` plus the new `projectId`. This is materially richer than readOnly/destructive/idempotent hints alone.

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 key distinction is front-loaded, but the body is one long paragraph with heavily nested parentheticals enumerating inherited vs reused artifacts, which is dense and hard to parse. Every clause carries information, but the structure would benefit from splitting into discrete statements for the gating, the inheritance list, and the spend notes.

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

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

For a complex, state-mutating, budget-spending operation with no output schema, the description covers return shape (projectId, typed outcome), spend/permission prerequisites, and the inheritance rules. There is little an agent would need that is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: confirm_spend is framed as a two-stage quote-then-commit gate tied to the same gating as project creation, and it clarifies the outcome typing (`cotizada`). Schoice and language semantics are largely covered by 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 the exact verb and resource (derive a rendition in another language from the project's current cut) and immediately draws the key semantic boundary: 'The SAME piece in another language — not a new piece'. An agent can distinguish this from generic project-creation or scripting siblings without opening any schema.

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

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

It gives precise when-to-use behavior for both modes: without confirm_spend it only prices, with confirm_spend=true it translates and writes. It also states the prerequisite (`Requires write`) and the wallet-coverage exception. It stops short of naming sibling tools it should be preferred over, but the usage conditions themselves are explicit.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, and the description goes well beyond that by disclosing pagination semantics, the ownership restriction, the speaker-for-whole-recording scope, and the `$0` cost. It does not describe rate limits or error conditions beyond the wordMap reasons, so it is not a full 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?

It is a single front-loaded block that opens with the resource and then unpacks the payload, with no filler sentences. The heavy parenthetical stacking (`startSec`, `endSec`, `ficha_pending`, `hearing_does_not_assert`) makes it dense and slows scanning, which keeps it from 5.

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 the return value, and it does so: record fields, `ficha` contents, speaker attribution, the phrase map with its field names, pagination handle, and the reason codes that explain an absent word map. For a read tool of this complexity, 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 description coverage is 100%, so both parameters are already documented and the baseline is 3. The description adds some linkage by tying `phrase_offset` to the response field `hearing.nextPhraseOffset`, which is a small but genuine semantic gain over the schema text.

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

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

"The whole record of ONE file of the material library" states a specific resource and scope (one file, full record), and the enumeration of what is returned (kind, size, duration, stage, ficha, speaker, phrases) makes the operation concrete. It does not name a sibling such as list_material, so differentiation is left implicit, which keeps it below 5.

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

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

The description tells the agent how to page (pass the previous answer's `nextPhraseOffset` as `phrase_offset`) and that only the credential's own files are visible, which are real usage constraints. It never says when to call this instead of `list_material` or the other listing siblings, so the alternatives guidance 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 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 flag destructiveHint=true and idempotentHint=true, but the description adds substantial context beyond them: exactly what is destroyed (staged edits only), what survives (committed versions and the cut), that the thread records the discard, and that `write` scope is required. It also states the cost ($0) and the outcome fields, though the idempotency claim itself is left to the annotation.

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

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

Three tight sentences, front-loaded with the primary effect and immediately followed by the safety boundary (what is untouched), then return values and prerequisites. Every sentence 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 destructive single-parameter mutation with no output schema, the description covers destruction scope, preservation guarantees, side effects (thread record), required scope, cost, and return payload. 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?

There is one parameter with 0% schema description coverage, so the schema does no work here, and the description does not explain project_id at all. It is a self-evident identifier in context, but the description provides no compensating meaning for 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?

Names a specific verb (drops) and resource (the project's staged conversation draft) and defines the resource precisely as free/paid edits on the current cut that are not committed. An agent can distinguish this from commit/accept_contribution 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?

Usage is implied: it explains that discarding returns the next edit to the cut start, which tells the agent the effect of choosing it. However, it never states when NOT to use it or names the alternative (commit) for the case where the staged edits should be preserved; that routing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description still adds substantial behavior: zero cost, no LLM call, the two-part answer shape (`launch` vs `economics`), the meaning of `economics.applies`, and exactly where funding checks stop the line (script before balance, studio build and final render after, status `waitingForFunds`). That is context no structured field carries.

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 correctly front-loaded — the first sentence carries the whole purpose — but the body is a single dense block with deep parenthetical nesting and untranslated enum values (`casa_invita`, `excede_bienvenida`), which slows scanning. Length is partly justified by the absence of an output schema, yet the sentence structure is heavier 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?

With no output schema, the description carries the return-value burden and does so thoroughly: field names, all reason codes, the applies/band/balance relationship, and the `vocabulary` escape hatch for non-English typed values. It stops short of stating authorization or credential requirements, though the operator-credential reason code partially covers that.

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 the schema itself documents nearly every parameter in depth, so the description's parameter content (source, cast, material, production) is largely restatement. The only genuine additions are the cross-tool framing ('accepts the same arguments as project creation', mapping idea→`prompt_seed`) and the note that material is excluded from price — both already hinted at in the schema text.

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

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

The opening sentence gives a specific verb and resource (price a piece and check whether it can launch) plus a decisive scope marker: 'BEFORE anything is spent — the same verdict the human cockpit shows.' Combined with '$0, no LLM' this cleanly separates it from the production siblings (`produce`, `commit`) without the agent needing to open 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?

It states the operating context (pre-spend dry run, accepts the same arguments as project creation) and explicitly routes one case to itself: 'price the change with `estimate`' under `excede_bienvenida`. It never names `produce` or `get_project_status` as the alternative for the opposite case, so the when-not half 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?

Beyond the annotations (write, non-idempotent, destructive), it discloses what is actually consumed (the organization balance, quota, daily free-action cap), the precise ordering of spend checks (the script is written before the balance is checked and settles with the first render; later stations stop with `waitingForFunds`), required scope (`write`), and the response shape (project id, pinned cast, status until `finalVideoUrl`, typically 20-60 min). That is materially more than the annotation flags convey and is exactly what an agent needs before triggering a paid mutation.

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 content is valuable but the ordering is poor: the first sentence is a billing caveat rather than what the tool does, and the paragraphs are dense with production-line minutiae (station ordering, `waitingForFunds`, pause reasons) packed into one block. It is not padded with fluff, but the front-loading fails the 'what does this do' test.

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 nine-parameter, deeply nested, paid, non-idempotent mutation with no output schema, the description covers prerequisites, spend gates, default-versus-override behavior, what gets returned and how long it takes. An agent can decide whether to call it and interpret the result without guessing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real cross-field semantics the schema does not: `creative_referent` may be a premium format with `requiresSpendConfirmation`, which then requires `production.confirm_spend=true`, and it describes the returned pinned cast (`cast.voice` / `cast.face`). The other eight parameters are left entirely to their already-rich schema descriptions.

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

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

The description states a specific verb and resource: "Creates a NEW project from an idea and launches it — the creation→edition crossing", and clarifies that the script is the first station of a production line, which separates it from siblings like `produce` or `rewrite_script`. However, the opening sentence is about billing rather than purpose, and the tool name (`generate_script`) versus the actual effect (creates a whole project) creates a naming tension the agent must resolve by reading further.

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 a clear default behavior (`production.auto_produce=true` runs the whole line) and the condition for choosing otherwise (`auto_produce=false` stops after the script so the piece can be edited before production), plus the premium-format spend-confirmation requirement. It never names sibling tools such as `estimate`, `produce` or `get_project_status` as alternatives, so the routing is implied rather than explicit.

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

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

Annotations already establish the read-only, idempotent, non-destructive, closed-world safety profile, and the description adds substantial operational context: zero cost, no push notifications, polling-only visibility, how fidelityReport is derived, the house critic's scope, and what run_id job results can contain. There is no contradiction with annotations.

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

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

The description is a dense run-on presentation of many return fields, with little structural separation. It is front-loaded with the overall purpose, but it is far longer than necessary and would benefit from bullets or grouping by return object.

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 return shape, the description does most of the work to explain lifecycle status, publication state, run objects, fidelityReport, job results, and next step. It is fairly complete for an agent to understand the response, though project_id semantics are left implicit.

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 only run_id has a schema description. The description meaningfully expands run_id by explaining that it is a job id returned by an asynchronous authoring, rewrite, or publication call and describing what the resulting job object reports, but project_id remains undocumented.

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

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

The description clearly states that this tool reports where a project stands across lifecycle status, production drive, funding wait, cut versions, runs, publication, final video, and next step. It is specific and resource-focused, but it does not explicitly distinguish itself from siblings such as get_project_vbp or list_versions.

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

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

The description explains a specific usage mode for run_id, namely retrieving an asynchronous job's status/result, and notes that progress is visible only through a new call because the server pushes no notifications. However, it gives no explicit guidance on when to use this tool versus sibling status/list tools.

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

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

Annotations already declare a safe, idempotent, closed-world read, and the description still adds substantial behavior: org-scoped lookups ('a project outside the caller's organization is not found'), paging semantics with complete/nextSceneFrom flags, 0-based indexing shared with edit ops, and a $0 cost note. This is rich context well beyond the annotation 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?

It is front-loaded with the resource definition, but the prose is a dense single block of em-dash clauses that is hard to parse, and several field explanations (artefactos, pantalla, duration_target_sec) run long. Given there is no output schema the detail is defensible, yet the structure is tangled rather than economical.

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 returns and does so thoroughly — page structure, scene references and their bases, factual backing, fidelity rows, duration semantics, and pagination behavior. Combined with annotations and fully documented parameters, an agent has what it needs 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 100%, so baseline is 3, but the description adds meaning: it ties scene_from to the prior answer's page.nextSceneFrom and explains that omitting it also returns the piece-level fields, and notes scene_count may be reduced to fit one result. That is genuine value on top of the schema text.

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

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

The description names the exact resource it retrieves — the project's Video Blueprint of the CUT (the structured scene score) plus cast.voicePin data — and distinguishes it from the pieces of the system it borrows from (edit ops positions, the project status's fidelityReport). It is a noun-phrase inventory rather than a verb-led statement, and the sibling list is only differentiated implicitly, but an agent can tell what it gets.

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 detailed mechanics for the paging parameters (no scene_from = first page with piece-level fields; with scene_from = a window) and notes the org-isolation constraint. It never states when to reach for this over get_project_status or the list_* siblings, so selection guidance is implied rather than explicit.

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

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

Annotations only declare the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds what the annotations cannot: the `write` permission requirement, the cost ('one critic call (small, seconds), plus a short translation'), and the persistent side effect ('The verdict is kept on the version as the critic wrote it'), which explains why this is not a read-only 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?

Purpose is front-loaded, which is good, but the body is a single dense paragraph saturated with backticked field names and nested parentheses that is hard to scan. Some of that bulk is defensible given there is no output schema, but the structure is poor.

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 return-value burden and does so thoroughly: score dimensions, per-scene notes with severity, `source` values, `factualAudit` semantics, `onScreenClaims[].outcome`, `placeholders`, and `inputs.script`. It also discloses permissions, cost, persistence, and judging scope, so an agent has everything needed to invoke it correctly.

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

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

Schema coverage is only 50%: `project_id` is undocumented in both schema and description, and the only parameter detail given ('Defaults to the head version') merely repeats the schema's own `version_id` description. With half the parameters undocumented, the description does not compensate for the coverage 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?

The description names a specific verb and resource ('the house critic's judgement of a script version') and immediately bounds the scope: 'Judgement only: it does not rewrite,' which separates it from rewrite_script. It also pins down what is out of scope (charts, periods), so an agent can distinguish it from siblings 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?

It gives clear operating context: the same critic the writing pipeline uses, defaults to the head version, requires `write`, and spends one critic call plus a translation. It stops short of an explicit when-to-use/when-not routing against siblings like generate_script or rewrite_script, though 'it does not rewrite' implies the boundary.

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 this a safe, idempotent read, so the bar is lower, but the description still adds real behavior: URLs are withheld unless the link was opened, results are limited to open plus recently-ended links, ownership is required, and the call costs $0. It also enumerates the returned fields (mode, state, caps, use, expiry, availability, limits), which matters since there is 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?

The scoping information and the URL-redaction caveat are front-loaded in a single dense sentence, followed by a short gloss on `availability`/`limits` and the ownership and cost notes. It is compact with no filler, though jargon like 'caps', 'use' and 'born with' costs a little clarity.

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

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

For a one-parameter read with no output schema, the description covers result scope, redaction behavior, authorization, cost and the shape of the returned object, which is nearly everything an agent needs to call it correctly. The only real gap is the meaning/format of project_id and what 'caps' actually contain.

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 a single required parameter at 0% schema coverage, the description must carry the meaning, and it only implies that the piece referenced ('a piece') is the project_id target without saying so or giving a format. The rest of the sentence is spent on return values rather than the input, leaving the sole parameter thinly documented.

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

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

The description gives a specific verb and resource ('Lists the upload links of a piece') and further narrows the scope to open links plus those that ended in the last 7 days, so an agent knows exactly what set is returned. It does not name a sibling (e.g. open_channel / close_channel) to contrast against, so it stops short of full sibling differentiation.

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

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

Usage is implied rather than stated: an agent can infer this is the inspection step before opening a link, helped by the mention that `availability` says whether the account can open one and `limits` the caps a new link is born with. The only explicit constraint is 'Only the piece's owner'; there is no explicit when-not or named alternative such as open_channel.

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 meaningful behavior beyond annotations: owner-only authorization, zero cost, and the contribution state lifecycle including the consequence that pending contributions are not used in the video. It does not discuss pagination or rate limits, but those are less critical for a simple list operation.

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

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

The description is a single dense sentence with a front-loaded purpose and useful parenthetical detail. Every clause contributes information about fields, states, access, or cost. The colon-heavy structure is slightly hard to parse but remains efficient.

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

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

For a read-only listing tool with no output schema, the description provides strong context: the source of the files, the returned fields, the state semantics, the owner-only restriction, and the cost. The main remaining gap is that it does not explicitly document the project_id parameter or the response envelope. These are minor compared with what is already covered.

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

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

Schema description coverage is 0%, so the description must compensate. It contextualizes the required parameter indirectly by describing the target as a piece, which maps to project_id, but it never explicitly defines project_id or confirms that the piece is identified by that parameter. The sole parameter is simple and required, so the ambiguity is limited.

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: listing files third parties sent to a piece via guest upload links. It also enumerates returned fields and contribution states, so the agent understands what is being retrieved. It does not explicitly contrast itself with the sibling accept_contribution, which is the closest related operation.

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 useful usage constraints: only the piece owner may call it and it costs $0. It also explains that pending contributions are not yet used in the video, implying the tool is for reviewing guest submissions. However, it does not explicitly say when to use this versus accept_contribution or other 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 readOnly/idempotent/non-destructive, and the description confirms it tersely with "Nothing is written. $0." Beyond that it discloses real behavior: uploads can be in progress or refused within the last day with a `stage` and `reason`, and the `ficha` runs asynchronously through `reading`/`ready`/`failed` while the file stays usable, including a `partial` outcome. That is substantive context annotations cannot carry.

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

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

It is a single dense block of run-on prose with em-dash chains and no bullets or sentences breaking the return-shape description from the filter description. Most content is load-bearing because there is no output schema, but the ficha-stage and speaker enumerations are packed tightly enough that an agent must parse carefully rather than skim.

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 returns, and it does: row fields, the `uploads` collection, the `ficha` lifecycle, `origin`/`provenance` with `stance`, and the speaker fields. An agent can call this with all-zero arguments and still predict the response shape.

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 baseline would be 3. The description nonetheless adds meaning the schema does not: it explains the `origin` values concretely, notes that with `asset_id` the file is returned whatever its origin, and unpacks what `handle` and `asset_id` yields (upload state; content hash).

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 resource (the creator's own material in the personal library) and enumerates exactly what each row carries — `assetId`, kind, filename, declarations, size, duration, usage count — so the agent knows this is a filtered listing tool, not a fetch or mutation. It does not explicitly distinguish itself from sibling listers such as `list_cast` or `list_referents`, which keeps it 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 states the selection rules for the alternate modes: `kind` keeps one kind of file, `asset_id` returns a single file, `handle` returns one upload's state, and `origin` chooses the source bucket with a stated default. It also gives a genuinely useful timing rule — the file does not wait for its `ficha`, so its `assetId` is already valid as material. It stops short of naming when to prefer a sibling tool instead.

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 read-only/idempotent/non-destructive safety, and the description adds meaningful context beyond them: result ordering (most recent update first), the archived-exclusion policy, the ~100+ project scale, and the '$0' cost signal. Return-shape detail compensates for the absent 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?

Dense but front-loaded: resource and ordering come first, then filters, then the exclusion policy. The nested parentheticals make it feel cramped, but no sentence is wasted.

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

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

With no output schema, the description supplies the returned field list (id, title, status, creative referent, renditionOf) and ordering, plus filtering and exclusion behavior. Together with fully documented params and safety annotations, nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds some value by listing concrete status values (EDITORIAL_BLOCKED, STUDIO_READY, FINAL_REVIEW, PUBLISHED) that the schema lacks as enums, but it gives no additional semantics for 'limit' and only restates 'q'.

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 projects in the caller's organization') and enumerates the returned fields, ordering, and rendition lineage. It is clearly distinguishable from siblings like list_versions, list_referents, or get_project_status, which operate on different resources.

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?

Implies its browsing/filtering role via 'q' and 'status' filters and explicitly rules out archived projects ('left out by design'). It does not, however, name an alternative tool for closed/archived projects or for per-project lookups, so the when-not routing is incomplete.

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 genuinely useful behavioral context beyond that: the '$0' cost disclosure, the null-means-platform-default convention with the fallback listed in `platformDefaults`, and the fact that each format flags whether it requires an explicit spend confirmation.

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

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

It is dense but front-loaded: the primary resource and the meaning of the id come first, followed by the secondary catalogues the call also returns. No sentence is filler, though the trailing '$0' and the long enumeration of auxiliary payloads make it heavier than a pure list tool usually 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?

With no output schema, the description carries the full burden of describing returns and does so thoroughly: the referent fields, the null/platformDefaults convention, the extra catalogues (duration profiles, output formats, budget tiers, writingProfiles, sceneOptions), the effect of both parameters, and the zero cost.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes slightly beyond the schema by tying `compact` to this tool's own payload — it names exactly what is dropped (pacing curve, per-format writing measures, writing catalogue) rather than the schema's generic 'heavy, rarely needed parts', and reinforces that `locale` governs the readable strings.

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 resource precisely — 'the creative referents — the formats a piece can be produced in' — and enumerates the fields each referent carries, which is far more specific than the title 'List formats'. It is clearly separable from siblings like list_cast, list_material or list_versions by content, though it never explicitly contrasts itself with 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?

Usage is implied rather than stated: 'The referent id is the value of `creative_referent` when a piece is created or priced' tells the agent how the output feeds other calls, which strongly hints this is a prerequisite lookup. However there is no explicit when-to-use/when-not guidance, no mention of estimate/produce as the downstream consumers, 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 already cover read-only, idempotent, non-destructive behavior, so the bar is lower. The description nevertheless adds real behavioral detail beyond that: the owner-only permission boundary and the partial-availability failure path returning `forbidden` with `extensions.reason=no_ofrecido`. It stops short of discussing pagination or volume limits.

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, then return fields, then constraints and error path, in one dense paragraph with no filler. It is jargon-heavy — `elegida`, `ficha`, `loDijo`, `frescura` — but each token carries information an agent needs to interpret results.

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 only two required parameters, no output schema and read-only annotations, the description carries the return-value burden itself and does so: it enumerates each returned field and the `frescura` enum values. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 50%: `scene_index` is already documented as 0-based in the schema and `project_id` is undocumented in both places. The description repeats the 0-based/VBP convention and reinforces that only one scene is queried, but adds no new meaning for `project_id`. Baseline 3 fits.

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 takes of ONE scene') and immediately defines what a take is (recordings the creator made reading the scene's script). The capitalized 'ONE' plus the definition make it unambiguous against siblings like list_material or list_versions.

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

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

Gives clear preconditions — 'Only the piece's owner' and '$0' — plus the single-scene scope, so an agent knows the access requirement and cost up front. It does not name an alternative for selecting a take (e.g. choose_take), so there is context but no explicit when-to-use routing.

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

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

Annotations already 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?

Beyond the annotations (which only assert non-read-only, non-destructive, non-idempotent), the description discloses a lot: the link is upload-only and cannot read the account, it expires, has caps on files and bytes, is revocable, and guest uploads are inert until the owner accepts them. It also names the returned fields (`link`, `channel` with state/caps/expiry), the `write` requirement, the specific failure mode, and that the call costs $0.

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 purpose, then behavior, then return values and failure mode — a sensible order with almost no filler. It is a single dense semicolon-chained paragraph, and trailing fragments like '$0.' are terse to the point of being cryptic, 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?

With no output schema, the description carries the return contract itself (the URL and the channel object with state, caps, expiry) and covers permissions, expiry, caps, revocation, and the acceptance step for guest uploads. Nothing an agent needs to invoke this 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 coverage is 80%, so the baseline is 3, but the description adds real meaning: `own` means the creator on another device with the link rendered as a QR code, while `guest` means a third party who must first read and accept an authorization text on the link page. It also implies ttl_hours is clamped by house bounds, which goes beyond the schema's 'house bounds it' wording only marginally.

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 (opens an upload link for ONE piece) plus the mechanism (a URL a device uses to upload files into the piece's material without signing in). The contrast with other channel tools is implicit but the scope is precise enough that an agent can tell this apart from request_upload or close_channel by the description 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?

Gives clear when-to-use context: two named modes with the scenario each fits, the constraint that only the piece's owner may call it, that it requires `write`, and the availability caveat returning `forbidden` with `extensions.reason=no_ofrecido`. It stops short of routing to explicit alternatives (e.g. close_channel to revoke, list_channels to inspect open links), 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?

Goes well past the destructiveHint/readOnly annotations by disclosing that the call requires write, consumes budget under the org quota and the daily free-action cap, and counts as one action. It also explains what the response carries (`dispatched`, `dispatch.reason`, `line`, `finalRender`, `finalRender.quote`) and that a new render only launches with confirm_spend=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 scoping before the conditional final-render branch. It is dense and long, with nested parentheticals about `dispatch.reason` and `finalRender` that slow an agent slightly, but nearly every sentence carries actionable 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?

There is no output schema, yet the description enumerates the meaningful response fields and their branches, so an agent knows what a successful call returns. Combined with the spend, auth, and idempotency caveats, nothing needed for correct invocation is missing.

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

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

Schema coverage is 50% and the description compensates by framing confirm_spend as 'only for a piece whose final is already delivered or failed' and describing the quoted-then-launched behavior. project_id is left implicit — only the phrase 'an EXISTING project' ties it to the required id 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 and resource: starts or resumes the production line of an existing project, and spells out the internal sequence (enrich → studio build → final render). It also draws a boundary by saying publishing is not part of it, which separates it from the publishing/ops 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?

Gives concrete when-to-use conditions: a project created without auto-production that has since been edited, or a line that stopped. It also covers the when-not case (final already delivered or final render failed) and the confirm_spend escape hatch. It never names a competing sibling such as run_op or direct, so the exclusion is inferred rather than explicit.

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

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

Annotations already mark this as destructive, non-idempotent and not read-only, and the description adds crucial context: it requires `write`, spends LLM budget charged at settlement, does not update the published final until a person renders it, and enumerates every outcome. No contradiction with annotations; the destructive hint is consistent with creating a new version and spending budget.

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 crucial precondition and spend-confirmation behavior are front-loaded, and every sentence carries behavioral information. It is dense and slightly run-on, but not padded with 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 supplies the return fields (`outcome`, `sourceStatus`, `quote`, `runId`) and all outcome values, plus auth, budget, and side-effect details. An agent has enough information to call it correctly 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 only 50%, but `confirm_spend` is well documented in the schema and the description adds the quote-only behavior and what confirmation actually launches. `project_id` is self-evident by name; the description adds no further semantics but does not need to.

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 ('Rewrites a piece') and pins it to a precise precondition: the source changed after production, with a concrete status marker. This distinguishes it from generic rewrite_script and other siblings that do not require a changed source.

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 when this tool applies (source status is `cambiada`) and explains the two modes: quote-only without `confirm_spend`, and paid launch with it. It does not explicitly name `rewrite_script` as the alternative for ordinary rewrites, leaving that routing 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?

Goes well past the annotations by disclosing the actual blast radius — the file survives in the owner's library and mounted scenes keep it — plus the no-op behavior with `removed: false`. It also states the authorization model (owner only, requires `write`) and cost (`$0`), which the annotations 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?

Front-loads the verb and effect, then layers the important caveats (not unmounting, no-op, permissions, cost) in short clauses. Every sentence carries distinct information; nothing is padding.

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 it still communicates the meaningful return signal (`removed: false`) and covers idempotency, authorization, and cost — everything needed to call it safely. The one gap is leaving the `project_id` parameter undefined for a two-required-parameter mutation.

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%: `asset_id` is documented in the schema, but `project_id` has no description in either place, and the description only alludes to the piece/owner relationship without mapping it to `project_id`. The description adds framing but no concrete parameter meaning beyond the schema.

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

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

States a specific verb and resource ("Removes a file from a piece's material") and immediately bounds it against the two nearest confusions: the file is not deleted from the library, and removing is not unmounting. An agent can distinguish this from assign_material or a mount/unmount operation without opening another 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 real usage context: it is the mechanism for declining a third party's contribution, and it is explicitly distinguished from unmounting a scene. It does not name a sibling tool (e.g. accept_contribution) as the alternative path, so the when-not guidance is implied rather than enumerated.

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?

Beyond the annotations (destructive, non-idempotent), it discloses the `write` scope requirement, the cost model (deterministic ops $0, LLM ops charged like a chat turn), per-op cost tags, and that responses carry an added deprecation notice. That is meaningful context the annotations cannot express. It does not cover failure/partial-success behavior when an op is routed mid-flight, which is the main remaining gap.

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-loading the deprecation notice is good and the per-op bullet structure is scannable, which justifies much of the length for a 12-op dispatcher. But there is real duplication: the closing paragraph states 'the deterministic ops are $0' twice, and 'The voice is cut from the recording at the next build, not synthesized' appears twice within `assign_narration_to_scene`.

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 dispatcher with free-form nested args, no output schema, and 12 sub-operations, the definition gives per-op purpose, cost, and argument semantics, plus scope and return-shape notes ('answers what that tool answers, plus a `deprecated` notice'). The missing piece is an explicit successor mapping so the agent can act on the deprecation notice rather than just observe 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 only 50% and `args` is an untyped free-form object described only as 'see description', so the description must carry the burden — and it largely does, spelling out required/optional arguments per op (scene_index, asset_id, shot_index, from_sec/to_sec, brief, order, voice_spec) including the 0-based indexing and defaults. It loses a point because `set_piece_fields` and `set_scene_fields` defer to 'validated by the schema' while listing only example keys.

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

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

The description opens with a specific status and role: a deprecated alias that routes each of 12 named edit ops to the tool that now owns it, plus a `deprecated` notice in the answer. The enumerated op list makes the resource scope unambiguous. It stops short of 5 because the underlying purpose is expressed indirectly ('the edit ops are split by cost between two tools') rather than naming the two tools the agent should target.

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 signals when-not-to-use (deprecated since 2026-09-27, kept until at least 2026-10-27) and defers routing to `invocableVia` in the op catalogue. However, the replacement tools are never named, despite `author_op` and `stage_op` appearing in the sibling list — an agent must perform a second lookup instead of being routed directly.

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 the consequences that matter: the courtesy is permanently consumed and does not return, the next project is not a courtesy, work already produced during the courtesy stays free, and all subsequent corrections/renders bill the wallet. It also states the `write` permission requirement, the $0 cost, and the returned fields (`leftCourtesy`, new `courtesy` verdict, `quote` with wallet balance) — a genuinely rich behavioral profile for a destructive mutation.

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 action and target are front-loaded in the opening clause, and the trailing fragments ('Requires `write`. $0.') are efficient. However, the body is one long run-on sentence with stacked parentheticals that makes it slower to read than necessary; splitting the trigger, the effect, and the return values into separate sentences would cost no 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 usefully enumerates the return values (`leftCourtesy`, `courtesy` verdict, `quote`), and it covers permissions, cost, irreversibility, and the trigger condition. The remaining gap is edge-case behavior — what an invalid or non-courtesy project_id yields, and whether repeat calls are no-ops given `idempotentHint: true`.

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%: `reason` is documented in the schema but `project_id` is bare. The description partially compensates by pinning the target as 'the account's first project (the one-minute piece the house produces)', which tells the agent which project_id is expected, but it never says what happens if a different project_id is supplied.

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 (leaving the house's courtesy on the account's first project) and identifies the exact piece involved — the one-minute capped-corrections/renders project. It is distinguishable from siblings like `produce` or `list_projects` because it explicitly frames itself as the alternative to opening a new project. It stops short of 5 because the domain term 'courtesy' is never defined plainly and the sentence must be parsed twice to extract the core action.

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

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

It states a precise trigger — the `payment-required` cap (`tope_correcciones_alcanzado` / `tope_renders_alcanzado`) — and names the alternative behavior (open a new project instead). What is missing is any explicit when-not guidance, e.g. what to do if the author wants to stop entirely or if the wallet balance is insufficient.

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?

Annotations only say it is a non-read-only, non-destructive, non-idempotent closed operation; the description adds substantial beyond that: no provider is called ($0), edits land in a draft that only becomes a version on commit, the result carries a coherence report where `hasBlocking` can be overridden with force=true, writes are skipped while an authoring turn is in flight, and `write` scope is required. Per-op behavior is also disclosed (e.g. set_title is sealed once committed, narration is cut from the recording rather than synthesized and survives voice regeneration).

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 paragraph is front-loaded and the per-op bullet list is a genuinely useful structure for a polymorphic tool. It is long, with some redundancy — 'Deterministic, $0' repeats on every bullet and the 'cut from the recording at the next build, not synthesized' sentence appears twice within assign_narration_to_scene.

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 nine-variant polymorphic tool with a 33%-covered schema and no output schema, the definition covers purpose, per-op arguments, side effects and reversibility, blocking conditions, auth scope, and what the result carries (the coherence report). Nothing material is missing 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 33% with a free-form `args` object, so the description must carry the load, and it does: each enum value of `op` gets a documented arg list with types, defaults, optionality and constraints (e.g. shot_index 0-based defaulting to the base shot, from_sec/to_sec segment semantics, with_picture being video-only and valid only on ai_image/ai_video/archive scenes, nested dicts merging and null deleting in set_scene_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?

Opens with a specific verb and resource plus scope: 'Stages ONE free edit op on a project — deterministic, no provider is called — into the project's conversation draft.' It further distinguishes itself from the paid re-authoring ops and creation-field tools, so an agent can separate it 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?

Clearly states the boundary: only free ops go here, paid re-authoring ops and creation fields have their own tools, and `invocableVia` in the catalogue maps each op to its tool. It also names the commit step that turns a draft into a version and the `authoring-in-progress` no-op condition. Lacks explicit named siblings (e.g. run_op, author_op, commit) so the routing cue is conceptual rather than literal.

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, which only say idempotent, non-destructive, non-read-only. The description discloses which assets get rebuilt (public copy, subtitle track, chapter count, poster, playback ladder), what is preserved (URL and publication date), the `write` permission requirement, the `$0` cost, and the two return outcomes including the idempotent `already_exhibited` path.

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 effect, then layers the trigger signal, the rebuild scope, and the return shape. The dense em-dash construction is efficient, though the first sentence is long enough that the trigger condition could have been broken out for faster scanning.

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

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

With no output schema, the description still explains the return payload (`outcome` and the exhibited run) and enumerates its values. Combined with the permission note, cost, idempotency behavior, and what is and isn't preserved, an agent has everything needed to decide and call 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%: `run_id` is described in the schema, `project_id` is not described anywhere. The description clarifies that the run must be a delivered final and defaulting behavior, but says nothing that disambiguates `project_id` beyond embedding it in 'the project's published gallery work'. Adequate given the schema does half the work, but it leaves a required parameter thin.

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 — repoint the published gallery exhibit at a newer final — and pins the scope with 'under the SAME public URL'. The parenthetical about `publication.gallery.exhibitsLatestFinal: false` makes it unmistakable against any sibling tool in the set.

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 the exact trigger condition: a piece re-rendered after publication, evidenced by `exhibitsLatestFinal: false` in the project status. It does not name an explicit alternative or when-not-to-use case, but no sibling appears to compete for this operation, so the context is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context: the read/write scope semantics, the rule that production is not charged to the wallet when the user operates the platform, and the '$0' cost signal, none of which appear in the annotations.

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

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

Front-loaded with the core answer ('The principal behind this credential') followed by a scoped list of returned fields and the cost. The single sprawling sentence with stacked parentheticals is dense and slightly hard to parse, but with no output schema every clause carries real 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?

With no output schema, the description must carry the return-value burden, and it does so field by field. Remaining gaps are minor: no statement of what happens when the credential is invalid or absent, and no indication of format for the wallet balance beyond the USD unit.

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

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

The schema declares zero properties, so there are no parameters to document and the baseline is 4. The description correctly adds no parameter discussion and instead spends its budget on the return payload.

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?

Opening clause 'The principal behind this credential' states precisely what the tool returns, and the enumeration of fields (credential kind/scopes, organization, user, wallet balance, legal, server version) leaves no ambiguity. It is trivially distinguishable from all siblings, which are project/script operations, though the distinction comes from subject matter rather than explicit differentiation.

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

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

There is no explicit 'use this when...' statement and no named alternatives, but usage is strongly implied by the content: an agent reading 'credential kind and scopes', 'wallet balance', and 'legal' infers this is the self-inspection tool for auth, billing, and legal acceptance state. The '$0' suffix hints it is cheap to call freely, which is a mild usage cue.

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