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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds genuinely useful context beyond that — it terminates a process tree, implying in-flight render work is killed rather than just flagged. However, it omits irreversibility, idempotency, and what happens to any partial output or artifacts already produced.

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

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

One tight sentence with the effect front-loaded and no filler. It is perhaps too brief for a destructive operation, but nothing in it is wasted or buried.

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

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

An output schema exists, so return values need not be explained. Still, for a destructive, non-open-world tool with one undocumented parameter, the description should at least connect job_id to its source and indicate whether cancellation is safe to retry or valid on already-finished jobs.

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

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

The single required parameter has 0% schema description coverage, so the description bears the full burden — but it says nothing about job_id. It doesn't indicate whether this is the id returned from generate_video, a storyboard id, or a status-polling key, which is exactly the ambiguity an agent would hit here.

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 ('Cancel') and a specific resource ('this job'), with an additional concrete effect ('terminate its render process tree'). It is clearly distinguishable from siblings like generate_video or get_video_status, though it doesn't explicitly name the job type (video render job) that ties it to generate_video.

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

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

No guidance on when to use it: nothing says it applies only to queued/running jobs, nothing about checking get_video_status first, and nothing about whether it is intended for stuck or misconfigured renders. The agent must infer the usage context from the tool name alone.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=false, so the mutation profile is known; the description adds real value by stating no model API is invoked (assistant-authored content), how durations are auto-derived from word count, and the safety rule that narration is shortened rather than silently cut. It does not say whether the plan is persisted or returned, which keeps it short of a 5.

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

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

Four front-loaded sentences that each contribute something: the scene shape first, then the no-API behavior, then the duration rule, then branding and text-fitting constraints. Dense but without filler; minor compactness loss from splitting the duration and branding rules into separate lines.

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

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

An output schema exists and annotations cover the safety profile, lowering the burden, and the description handles the trickiest part (untyped scene objects and duration derivation). Still, for an 8-parameter creation tool with zero schema descriptions, leaving the audio/visual parameters (voice, aspect, music, caption_style, music_volume) unexplained and omitting any mention of preview/generate sequencing leaves clear gaps.

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

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

Schema coverage is 0% across 8 parameters, so the description must carry the load. It documents the nested scene fields (text, query, asset_id, duration_seconds), branding keys (title, footer, color, logo_asset_id) and the total duration_seconds semantics, which is valuable given the untyped scene items. However, music, voice, aspect, music_volume and caption_style receive no mention at all.

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

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

States a specific verb and resource ('Plan explicit scenes') and enumerates the scene fields (text, query, asset_id, duration_seconds), so the agent knows this builds a storyboard plan rather than rendering or fetching one. It never names siblings like generate_video or preview_storyboard, so differentiation is only implicit from the word 'plan'.

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 line 'The assistant writes the scenes; no model API is called' clarifies the mode of operation but not when to choose this over preview_storyboard or generate_video. The duration rule ('Set every scene duration or let the planner divide the total by word count') is a useful usage instruction, but there are no explicit exclusions or sequencing guidance.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true; the description adds genuine value by revealing this is an asynchronous job that must be polled rather than a synchronous return. However it says nothing about what allow_network actually permits, whether the render consumes credits/time, or what happens on failure – notable gaps for an open-world mutation tool.

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

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

One compact clause pair with the action front-loaded and the follow-up step appended; nothing is wasted. It is arguably too terse for a tool with two undocumented parameters, but that is a completeness issue rather than verbosity.

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?

An output schema exists, so return values need no explanation, and the async polling instruction covers the main workflow need. The unexplained allow_network flag and absent preconditions leave real gaps for a job-starting mutation tool with open-world access.

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 carries full burden, yet it only vaguely gestures at storyboard_id via 'the selected storyboard' and never explains allow_network at all – the single most non-obvious parameter given openWorldHint=true. Format and expected value of storyboard_id are also unstated.

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 ('Start an exact-duration render of the selected storyboard') and explicitly names the sibling to poll (get_video_status), separating it from preview_storyboard, cancel_video and get_video_results in the sibling list.

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 implies the call is the kickoff step of an async flow and names the follow-up tool (get_video_status). It does not state prerequisites (e.g., that a storyboard must first be created and its scenes selected) or when to prefer preview_storyboard instead, so no explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and locality are covered. The mention of 'limits and privacy boundaries' signals that returned content carries constraints and data-handling rules, which is useful extra context, but the description does not say the call is side-effect free, cheap, or cacheable, and the output schema carries the rest.

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

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

A single front-loaded sentence with no filler. Every noun in the enumeration maps to a distinct category of returned 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 parameters, a read-only annotation, and a full output schema describing the return shape, the description needs only to establish scope, which it does. The one missing piece is sequencing guidance — telling the agent to consult this before invoking voice or provider-dependent tools.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. Schema coverage is nominal since the arguments object is empty.

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 ('Report') and enumerates the resource contents: installed voices, provider options, limits, and privacy boundaries. This is clearly distinct from the media/video siblings, none of which describe capability introspection, though the phrasing is a field list rather than a single crisp purpose statement.

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

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

No explicit when-to-use guidance is given, and no sibling is named. The agent must infer that this is a discovery call to make before choosing voices in preview_voice or options in generate_video — that inference is reasonable but not 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds only that the returned plan carries scene-to-media assignments, which is mild but real context; nothing about resolution failures or what 'saved' implies.

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

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

A single, front-loaded sentence with no filler. It is short for good and bad reasons — no waste, but also no elaboration.

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?

An output schema exists, so return-shape detail is unnecessary, and annotations cover safety. Still missing is any guidance on the id parameter's provenance and how this differs from the preview sibling, leaving the agent with an incomplete decision 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?

Schema description coverage is 0% and the sole parameter storyboard_id is never mentioned in the description. The name is self-explanatory, but there is no compensation for the missing schema documentation (e.g. that it must reference an existing saved storyboard).

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 verb 'read' plus 'saved plan and its scene-to-media choices' conveys retrieval of a persisted storyboard, but it never uses the word 'storyboard' and gives no basis for distinguishing it from siblings like preview_storyboard or get_video_results. Purpose is inferable, not precise.

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 statement of when to use this versus preview_storyboard (preview) or search_media (find media). The agent must guess that this is the lookup-by-id path.

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

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

The readOnlyHint/openWorldHint annotations already establish this as a safe, local read, so the description only needs to add context. It adds the fact that results are packaged artifacts, but says nothing about what happens if the job is incomplete, queued, failed, or nonexistent.

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

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

A single front-loaded sentence with no filler. It is efficient, though the space saved is spent on enumerating return fields rather than on the information that is actually missing.

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?

An output schema exists, so listing MP4/SHA-256/credits/duration is largely redundant, while the real gaps — job lifecycle prerequisites and job_id provenance — go unaddressed. Adequate to invoke, but not complete.

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

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

Schema description coverage is 0% for the single job_id parameter, and the description does not compensate at all — it never mentions job_id, where it comes from, or its expected format. The parameter is therefore undocumented in both schema and prose.

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?

Uses a specific verb ('Retrieve') tied to the video-result resource and enumerates what comes back (MP4, SHA-256, credits, quality report, duration). It is understandable on its own, but it never contrasts itself with the close sibling get_video_status, which an agent could easily confuse it with.

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 guidance on when to call this versus get_video_status, nor any precondition such as the job having finished rendering. The agent gets no signal that job_id must refer to a previously submitted generate_video job.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and locality are covered. The only added signal is that failures surface as a "bounded actionable failure message", which is vague - it does not say what a bounded message means, whether it is retryable, or what terminal states exist.

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 terse to the point of being under-specified rather than concise - a fragment with no subject, no verb mapping to the tool, and nothing front-loaded about the resource being queried.

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?

An output schema exists, so return-shape details are not required, but for a single-param polling tool the description should still identify the resource, the meaning of job_id, and the polling context. None of that is present, so the definition is not sufficient on its own.

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% and the single parameter job_id is completely undocumented in both schema and description. A caller gets no hint that job_id is the identifier returned by generate_video or that it must be a resolved job.

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

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

The description is a sentence fragment that never names the resource: "Read progress" of what is left implicit, relying entirely on the tool name. Against siblings like get_video_results and get_storyboard, it gives no basis for telling a status/progress poll apart from a results fetch.

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 statement of when to call this versus get_video_results, get_storyboard, or cancel_video, and no mention of polling after generate_video. The agent must infer the entire workflow from the tool name alone.

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

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

Annotations already disclose that this is a mutation (readOnlyHint=false) in a closed-world setting. The description adds the staging precondition and mentions rights metadata, but it does not explain side effects, permissions, or failure behavior.

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

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

A single front-loaded sentence with no wasted wording. The key constraint appears immediately.

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 four-parameter mutation tool with no schema descriptions, the definition is too sparse. It covers the filename precondition and hints at rights metadata, but does not explain required title, creator, or license_name semantics.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It mentions filename and rights metadata, but leaves title, creator, and license_name unclear, including the license default.

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: importing a media filename from the operator's managed inbox. The description is clear but does not differentiate this tool from siblings such as search_media, so it falls short of a 5.

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

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

Gives clear context for when to use it: only with a filename already staged by the operator in the managed inbox. It does not name alternatives or explicit when-not cases, which keeps it below a 5.

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

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

Annotations already disclose readOnlyHint=false and openWorldHint=true, so the description does not need to restate safety. It adds that the result is an inline contact sheet plus scene timeline, but it does not explain side effects, why it is not read-only, or how network access affects behavior.

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

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

The definition is a single front-loaded sentence with no filler; the purpose and return content appear immediately.

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?

Without an output schema, the description should explain the return shape more fully, and with openWorldHint=true plus an allow_network parameter it should clarify network implications. It names the returned artifacts but leaves key invocation-relevant behavior undocumented.

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, but it never mentions storyboard_id or allow_network. 'Its scene timeline' only weakly implies a storyboard target, and allow_network is entirely unaddressed.

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 ('Return') and concrete outputs ('contact sheet inline and its scene timeline'), making the preview purpose clear. It is distinguishable from get_storyboard by its semantic-review framing, though it does not explicitly name a sibling alternative.

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?

'For semantic review' implies the usage context, but there is no explicit guidance on when to use this versus get_storyboard, preview_voice, or generate_video, and no when-not conditions.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=false, and 'Create a ... WAV' is consistent with a write. The 'No text leaves the computer' line usefully reinforces the closed-world/privacy profile, but nothing is said about where the file is written, whether it is overwritten or cleaned up, or cost/latency of synthesis.

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

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

Two tight sentences with zero filler, and the action plus its privacy guarantee are front-loaded. Nothing needs to be trimmed.

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?

An output schema exists, so return values need not be explained, and defaults make the tool callable with no arguments. However, with 0% parameter coverage the agent gets no help on the text/speed/voice inputs or on what to do with the resulting WAV file, leaving a real gap for a synthesis tool.

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

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

Schema description coverage is 0% for three parameters, and the description never mentions text, speed, or voice. Only the word 'narrator' loosely hints at the voice parameter, and the non-obvious default ('af_heart') and speed units are left entirely unexplained.

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

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

States a specific verb+resource: 'Create a short local WAV preview,' scoped to narrator selection. An agent can tell it produces an audio preview rather than a storyboard preview, but the description never names or contrasts a sibling (e.g. preview_storyboard) explicitly.

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

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

'before choosing a narrator' gives a timing cue for use, but there is no guidance on prerequisites, when not to use it, or which tool actually performs the narrator selection. Usage is implied rather than 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 give openWorldHint=true and readOnlyHint=false, but the description adds little beyond hinting that results carry source pages and license notices. Critically, it never explains that network access is disabled by default (allow_network=false), so an agent cannot predict what happens on a default call. The "find" framing also sits awkwardly against readOnlyHint=false without clarification.

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

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

One short sentence with no filler, but this is under-specification rather than concision — it omits nearly everything an agent needs. Length is fine; content density is not.

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?

An output schema exists, so return-shape explanation is not required. However, for a 4-parameter, open-world search tool with 0% schema coverage and a default-off network flag, the description leaves the agent unable to construct a correct call or anticipate failure modes.

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% across four parameters, and the description compensates for none of them: query semantics, the mixed/image/video kind enum, the providers allowlist, and the allow_network flag are all undocumented. The most consequential parameter, allow_network (default false), is invisible in the description.

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

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

"Find licensed candidates" gives a verb but the resource is only inferable from the tool name; the description never says it searches images/videos across providers, nor that it returns license-annotated results. It is distinguishable from write-side siblings like import_media or generate_video, but only by implication.

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 only workflow guidance is "consult source pages and notices before selecting them," which points vaguely at select_scene_asset without naming it. There is no statement of when to use this versus import_media, and no mention that allow_network defaults to false, which materially changes when the tool is usable.

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

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

The description adds significant behavioral context by explaining the non-side-effect behavior of the mutation (not regenerating scripts or other choices), which is a high-value detail beyond what the annotations or schema convey.

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

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

The definition is a highly efficient single sentence that packs the action, target, and behavioral constraints into one concise statement.

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 this mutation tool, it is extremely complete. It explicitly addresses the scope of change and lack of downstream cascading effects, which is exactly the context an agent needs 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?

With 0% schema description coverage, the description must carry the semantic weight. It establishes that the inputs relate to 'scene' and 'media choice,' providing necessary conceptual meaning for the required IDs.

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

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

The description clearly identifies the action ('Replace') and the resource ('scene's media choice'), providing a distinct purpose that differentiates it from sibling tools like search_media or generate_video.

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

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

It provides a critical constraint for usage: the replacement is performed 'without regenerating its script or other choices.' This clearly defines the boundaries of the tool's functionality.

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