Clypmint

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

Adds real context beyond annotations: saves a playable project, unsupported changes refuse without rebuilding, retries must reuse operation_id and exact inputs, consumes the account's direct-edit allowance, and is free of credits. It doesn't spell out what state is overwritten or what the destructive mutation affects, which would complete the picture for a destructiveHint=true 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?

Front-loaded and dense with useful facts; most clauses earn their place. The semicolon-chained phrasing and 'Cost: Free: no credits' are slightly awkward, but 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?

Given an output schema exists, return values needn't be described. For a destructive, versioned mutation it covers prerequisites, failure mode, retry behavior, and billing. It leaves the direct-edit allowance's limits and the precise 'unsupported changes' condition 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 100%, so the baseline is 3. The description still adds value by naming the source of the scene shape (get_project_context), specifying which output_id and base_version to pass, and reinforcing retry semantics for operation_id.

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

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

States a specific verb+resource ('Insert one scene') and a concrete placement rule ('after null inserts it at the start'), which separates it from move_scene, remove_scene, and replace_scene_screen. An agent can identify the operation 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?

Explicit prerequisites: 'Read get_project_context first and pass its base_version and selected output_id', and it routes file generation to 'check_video with_download'. It doesn't explicitly say when to prefer siblings like replace_scene_screen or how it differs from move_scene, but the workflow context is strong.

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; the description resolves the apparent tension by explaining that the change is versioned ('saves it as the style's next version... earlier versions are kept'), which is exactly the context annotations cannot carry. The retry guidance reinforces idempotency but largely repeats the operation_id schema text.

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 what the tool does, then side effects, then the retry rule. No filler and every clause carries operative 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?

An output schema exists and annotations cover the safety profile, so the description only needs to supply the versioning model and retry discipline, which it does. Minor gaps remain around failure behavior (e.g., what happens if the plain-words request is ambiguous) and the role of style_id.

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 operation_id the sole documented field, so the description must compensate for `change` — and it does, specifying that the value is free-form natural language with worked examples. `style_id` is only implied by 'one of the linked account's saved styles' and never gets explicit semantics, which keeps it off 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 ('Change one of the linked account's saved styles') and narrows the input modality to plain words, which separates it from set_caption_style, copy_style, and browse_styles. The examples ('bigger yellow captions, no zooms') make the operation concrete rather than abstract.

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 example phrasings imply what kind of request belongs here, and 'every later video in that style follows it' signals the scope of effect. But no sibling is named and no when-not-to-use guidance is given, so the agent must infer how this differs from set_caption_style or edit_video.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), yet the description adds non-obvious behavioral semantics: motion defaults to inputs.voice:none, an explicit voiceover overrides that while preserving the visual style and aligning visuals to speech, and narrated faceless styles use inputs.voice:narrator. That is meaningful default/override disclosure beyond the structured annotations, though return-format expectations remain thin.

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 in the first clause, and the dense semicolon-separated clauses each carry content (format types, voice defaults, narrator catalog, audition guidance). It is information-heavy for a simple listing tool, but no sentence is 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?

For a no-parameter read tool with an output schema, the description is complete enough: it explains what is returned in categorical terms, the voice/default behavior, and how to act on auditions. Some enumerated return fields partially duplicate the output schema, but the behavioral rules (motion voiceover override, narrator voice) are what the schema would not convey.

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 (additionalProperties: false), so there are no parameter semantics to explain; baseline 4 applies. The description instead documents referenced fields of returned styles (voice, style_version), which is relevant context rather than parameter guidance.

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 verb+resource ('Show ready styles/copies') and enumerates what the listing contains: content format, frame formats, jobs, best_for, inputs, style_version, plus narrator descriptions and audition URLs. It is clearly a read/discovery tool, but it never names or distinguishes itself from siblings like adjust_style, copy_style, or apply_edits, so an 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 offers workflow guidance ('Recommend suitable returned styles, never invent private IDs', 'Listen/show auditions before selecting an undecided voice') that shapes downstream behavior, which is genuinely useful. However, it gives no explicit when-to-use/when-not-to-use framing against the sibling style tools, so usage is only implied.

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

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

Annotations declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: the blocking wait duration and its platform variance, the self-refreshing card that makes re-polling wasteful, and that download link creation is opt-in via with_download. No behavior contradicts the annotations.

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

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

Purpose and the key waiting behavior are front-loaded, and nearly every clause carries operational meaning. It is parenthetical-heavy and rambles in the middle, so it is dense rather than wasteful but not maximally tight.

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 unnecessary, and the description fully covers states and download behavior. However, with six optional parameters and no required fields, the description never resolves which of video_id/import_id/output_id to pass, leaving real ambiguity for an agent assembling the call.

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%; the description does explain job_id's role (revise_video's change report) and with_download's side effect, matching the schema-documented params. But video_id, import_id, and output_id are bare strings in both schema and description with no indication of which identifier to supply in which situation.

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 ("Check a video and show it") and enumerates the state machine it surfaces (waiting, uploading, editing, ready, draft, failed). It is clearly a status/polling tool, though it never names which sibling it replaces (e.g. list_videos, get_video_activity) so an agent must still infer 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?

Explicit when-to-call guidance: it waits up to 20s (50 in Claude) so only re-call right away if the user is waiting, and the card self-updates. It also prescribes per-state actions (draft: say it's a rough cut and offer next_step; failed: state the problem and next_step) and the condition for with_download (only when the user wants the file).

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, yet the description still adds meaningful behavior: credit economics (monthly included copies, then 100 credits each), rough timing for match (a few minutes), the approximate-vs-deep fidelity difference, and that in-progress/failed copies surface in browse_styles with remaining time or a stop reason. It does not explain what the destructiveHint implies (e.g., whether an existing style is overwritten), which is the one notable 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?

The lead sentence front-loads purpose, and the mode/cost/dry_run sentences each carry distinct information. It is somewhat dense with colon-chained clauses, and the mode economics partially repeat the enum description in the schema, but there is little outright 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 an output schema present, return values need no explanation, and the description covers the operationally critical facts: mode selection, cost and inclusion rules, dry-run behavior, and where to check status. It is slightly incomplete on the undocumented name/format parameters and on the destructive semantics flagged by annotations.

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

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

Schema description coverage is only 43%, and the description compensates well for mode (elaborating depth, cost, and inclusion beyond the enum doc) and dry_run, plus confirming reference can come as link or file. It says nothing about name, format (talking/faceless/motion), or reference_url, so several parameters remain undocumented across both the schema and 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?

"Build a reusable editing style from one reference video shared by link or file" gives a specific verb (build), a specific resource (reusable editing style), and the required input source (reference video via link or file). It also differentiates from the sibling browse_styles by positioning that tool as where in-progress/failed copies are tracked.

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 clone-vs-match tradeoff is spelled out with concrete conditions: clone is the deep default that consumes a monthly style copy then 100 credits each, match is fast, approximate, and included for all accounts, and dry_run answers cost/eligibility without starting anything. What's missing is routing guidance against siblings like adjust_style or apply_edits, so the agent knows when this tool is the right entry point versus modifying an existing style.

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 mutation, idempotency, and destructiveness, but the description adds substantial behavioral context: exact credit costs, dry_run behavior, script-length refusal rules, voiceover alignment behavior, style format constraints, and retry guidance preserving operation_id.

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 the body is an extremely dense run-on paragraph. Many details are necessary for 18 parameters, yet the lack of structure and sentence economy makes it harder to scan than it should 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?

Given the 18-parameter complexity, 50% schema description coverage, and the existence of an output schema, the description supplies nearly all missing decision context. It covers creation semantics, cost, retries, output handling, and publishing constraints.

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 the description compensates heavily: exactly one of idea or script, script length implied by seconds, style_id plus style_version for saved styles, voice defaults including none for motion, music_bed only when true, and staging-key usage for imported assets.

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: make a faceless video without filming or uploading footage. It distinguishes itself from siblings by naming create_videos for multiple videos, plan_content for monthly posts, browse_styles for style inspection, and check_video for progress.

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 explicitly routes the agent: use create_videos for several videos at once and plan_content for a month of posts. It explains dry_run as a cost-answer mode that starts nothing, and directs agents to check_video for progress and downloads.

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 destructive=true and idempotent=true, and the description adds real context: every item is validated before any rendering starts, retries are safe because each item is keyed on operation_id.N, and dry_run returns cost without starting work. The only shortfall is that it never says what makes this destructive or how partial failures are reported, though it does say validation happens up front.

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 batch limit and routing, which is good, but the pricing is stated twice in near-identical wording, padding the definition. The long inline voice list also bloats a sentence that the schema already documents.

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 nested, 4-parameter batch mutation with an output schema and annotations, the description covers the cap, the per-item idea-or-script requirement, shared defaults, idempotency, dry-run, cost, and the next steps. An agent has everything needed 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 100%, so baseline is 3, but the description adds meaning beyond the schema: it lists the shared defaults by name (seconds, style_id, formats, voice, sound_effects), enumerates the voice options, and ties seconds and extra formats to cost impact. It still leaves asset_ids, style_version and music_staging_key unexplained.

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

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

States a specific verb and resource ('make up to 10 faceless videos in one call') and distinguishes itself from singular create_video and from plan_content for a month of posts. An agent can route between batch, single, and planning tools 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?

Explicit routing rules: more than 10 videos means batches of 10, a month of posts means plan_content, and the follow-up path is check_video then schedule_plan. It also names the dry_run condition for price checking before committing.

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

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

Annotations declare destructive/idempotent/not-readOnly, and the description adds genuinely new behavior: it saves a playable project rather than producing a file, unsupported changes are refused without rebuilding, the operation consumes the account's direct-edit allowance, and operation_id must be preserved on retries. These are exactly the traits an agent needs before calling 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?

Front-loads the action and scope, then prerequisite, side effects, retry, and cost in short sentences with no obvious filler. The telegraphic style ('Cost: Free: no credits') is slightly clipped but still 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?

Output schema exists and annotations cover the safety profile, so the description only needs to cover prerequisites, side effects, retry/idempotency, and cost – all of which it does. A destructive mutation with a required sequencing dependency is fully explained.

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

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

Schema description coverage is 100%, so the schema already documents words, video_id, output_id, base_version, and operation_id. The description adds only the sourcing hint that base_version and output_id come from get_project_context; with the schema doing the heavy lifting, baseline 3 is appropriate.

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

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

States a specific verb and resource ('Remove footage time for the inclusive transcript word range') and explicitly distinguishes it from the nearby layer-removal operation ('This removes speech, unlike removing a graphic layer'). An agent can tell what it does and what it is not without opening the schema.

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

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

Gives a concrete prerequisite sequence ('Read get_project_context first and pass its base_version and selected output_id') and routes file retrieval to a sibling ('request a file separately with check_video with_download'). It lacks an explicit statement of when not to use it versus the layer/scene removal siblings beyond the speech distinction, so not quite a 5.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=true, and the description usefully adds that removal is reversible and that text is locked once an idea enters production. However, the trailing 'Free. Cost: Free: no credits' is repetitive boilerplate, and it never clarifies what exactly gets replaced on a partial update.

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

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

The critical constraint (editable before production) is front-loaded and the field list is compact. The final 'Free. Cost: Free: no credits' clause is redundant filler that weakens an otherwise dense sentence.

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 the annotations cover the safety profile, so the description need not explain returns. But for a destructive mutation it never says whether omitted fields are preserved or cleared, which 'words' are locked once production starts, or what plan_id must reference — gaps an agent needs resolved before calling.

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

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

With only 0% schema description coverage, the description carries the burden well: it explains that 'n' is the idea number and maps the editable fields to title, hook, script, caption, hashtags, post_at and platforms, plus the true/false semantics of 'removed'. It adds nothing about plan_id, and the value constraints (max 31 items, 10 hashtags, 3 platforms) are left entirely to the schema.

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

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

A specific verb plus resource ('Change ideas by number') with an explicit list of the fields that can be edited. It also draws a boundary against the sibling update_post for already-scheduled posts, so an agent can identify the right tool 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?

States the precondition 'before they are made or posted' and names the alternative path explicitly ('a scheduled post changes with update_post'). It also gives the when-to-use rule for removal versus restoration ('true to drop one, false puts it back'), leaving nothing 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?

Beyond the annotations, the description discloses credit costs, dry_run behavior, the 15-minute private upload link, that editing starts when the video lands, one upload per video, and that operation_id must be preserved on retries. These details materially inform an agent about side effects and operational constraints.

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

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

The description is front-loaded with the core action and field-mapping rules, and most clauses carry useful routing or operational information. It is nonetheless a dense single paragraph with some overlap against schema descriptions, which slightly reduces scanability despite the complexity warranting detail.

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 31-parameter mutation tool with an output schema, the description covers the essential workflow, alternatives, upload handling, cost, dry_run, retries, references, and style selection. Combined with the rich schema and annotations, an agent has enough context 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 description coverage is already high at 84%, so the schema carries much of the parameter burden. The description still adds valuable cross-parameter guidance: mapping user requests to kind, length, style_id, music staging, formats, instructions, purpose, hooks, shorts, clips, reference_url, and cost-related dry_run behavior.

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: editing the user's own footage into a finished video. It explicitly distinguishes this from create_video when there is no footage, from revise_video for changes to an already-made video, and from footage_from for a separate new edit of the same footage.

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

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

It gives explicit routing rules: use browse_styles once before choosing style_id, use import_asset for songs, use create_video for an idea or script, use revise_video or direct edit tools for changes to an existing video, and use reference_url for 'like this one'. It also explains when to omit style_id when reference_url is set.

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 destructiveHint/idempotentHint annotations, the description discloses a non-obvious invariant ("Each spoken word keeps a caption word"), a quota ("5 a day per video"), and cost ("Free: no credits"). The timing-never-moves guarantee also clarifies what destructiveHint actually touches here — the words/colour, not the timeline.

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 constraint, then routes to alternatives in a compact run of sentences. The trailing "Cost: Free: no credits." largely restates the earlier "Free; 5 a day per video" and could be dropped without loss.

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 an output schema present and annotations covering safety, the description supplies what structured fields can't: the fixed-timing invariant, quota, cost and the remember/revise_video fallback. The only unhinted parameter is base_version, whose role in conflict handling an agent must infer.

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

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

Adds real meaning over an already 83%-covered schema: lines are sourced from get_project_context captions and carry from/to/text, and replace is explained as a global word swap with a concrete brand-name example ("Clip Mint" → "ClipMint"). color, base_version and operation_id get no prose, so it stops short of full coverage.

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 ("Fix caption words or the key-word colour of a finished video") plus a hard scope boundary — "without a new edit; timing never moves" — that separates it from revise_video and edit_video. An agent can pick this over siblings without opening any schema.

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

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

Gives explicit routing: rewrite lines pulled from get_project_context captions, or use replace for brand names/people. It also names the escape hatch for cases this tool can't handle ("a 2-word name cannot become 1 word here: use remember plus revise_video"), which is exactly the when-not guidance most definitions omit.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: the downstream effect ('Later videos leave it out') and the cost ('Free: no credits'). It does not state whether the removal is recoverable, but the added effect and pricing info go beyond the structured fields.

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

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

Three short sentences with zero waste; the core action and its id source are front-loaded, with effect and cost as supporting detail. Nothing could be removed without losing 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?

An output schema exists, so return values need not be explained, and the destructive idempotent nature is covered by annotations. What remains thin is the absence of any irreversibility or recovery note for a destructive operation, though the coverage is otherwise adequate for a one-parameter tool.

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

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

Schema description coverage is 100% and the single memory_id parameter is fully documented in the schema with a reference to list_memory. The description mentions the same source but adds no format or syntax detail beyond it, so the baseline 3 applies.

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

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

States a specific verb (forget) and a precisely scoped resource (one remembered preference by its id from list_memory), which cleanly distinguishes it from the sibling remember (adds a preference) and list_memory (enumerates ids). It stops short of naming remember as the inverse operation, but the resource is unambiguous.

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

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

The phrase 'by its id from list_memory' implicitly tells the agent to source the id from the sibling list_memory tool first, which is useful routing. However there is no explicit when-to-use or when-not-to-use guidance (e.g., preferring disable over delete, or that this is irreversible).

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 useful scope context ('return only' identity/labels) and the intended workflow (account linking), though it says nothing about auth requirements or rate 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?

Three short sentences, front-loaded with what is returned, then the purpose, then the routing instruction. 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?

An output schema exists, so return values need no explanation, and the tool is a parameterless read. The description covers scope, purpose and the sibling alternative, leaving nothing an agent needs 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?

Zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify beyond the fact that no input is required, which the empty schema already conveys.

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

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

States a specific action (return) on a specific resource (the account's stable identity and display labels), and constrains scope with 'only'. It is clearly distinguishable from sibling get_profile, which the description explicitly names.

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

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

Gives an explicit use case ('Used for account linking') and an explicit redirect for the adjacent need: 'For account rights, credits and usage use get_profile.' This is exactly the when/when-not/alternative pattern.

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 new context beyond that: the cost ('Free: no credits') and the full set of possible idea states, which tells the agent what a successful read can contain.

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. The eight-state enumeration is long but functional, since it tells the agent what values to expect rather than padding the text.

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?

Return values are covered by the existing output schema, and annotations handle safety, so the description's remaining job is cost and content shape, both of which it gives. The gaps are minor: the required parameter's identity and the distinction from plan_content/edit_content_plan are not spelled out.

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% and the single parameter plan_id has no description. The description never explains what a plan_id is, where it comes from, or its required pln_<hex> format, so the only parameter is undocumented in both places.

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

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

The description states a specific verb and resource: 'Read a calendar from plan_content,' and enumerates the returned idea states, so an agent knows exactly what it gets back. It doesn't name the sibling it contrasts with (plan_content, edit_content_plan), so the differentiation is implied via 'Read' rather than 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?

There is no when-to-use statement or alternates named. The read-oriented phrasing hints that this is for inspecting an existing plan rather than creating or editing one, but the agent must infer that from sibling names 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, idempotentHint, closed-world and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral content by disclosing exactly what the read returns — credits consumed, credits included this billing month, renewal timing, and videos used.

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 that leads with the returned resource before the purpose clause. The parenthetical credit detail is dense but every element maps to real return content, so nothing is wasted.

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

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

A no-argument, read-only tool with an output schema and full annotation coverage needs little more than a scope statement, which this provides. The only unstated detail is failure behavior when no profile is linked, a minor omission given the output schema carries the return contract.

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

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

The tool takes zero parameters, so the baseline is 4; there is no parameter surface for the description to clarify or for the schema to obscure.

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 resource ('the Clypmint profile linked to this request'), and enumerates the payload (credits used/included/renewal, videos used). This is clearly distinct from siblings like get_account_identity or get_project_context, though it never names an alternative to disambiguate 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?

The closing clause 'so you can say what a request will use before spending' gives a concrete usage context: consult this before committing credits. It stops short of naming when-not-to-use or an alternative sibling, so it is clear context without 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 readOnly/idempotent/non-destructive, so the safety bar is met; the description still adds real context: no visual card is returned, no second model round is needed for edits, and canvas image IDs refer to assets already present in this version. Pagination behavior is mentioned but page granularity and bounds are not.

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?

Five sentences, front-loaded with what is returned, then parameters, then downstream usage, then return-shape caveat. Dense but every sentence carries information; only the phrasing is slightly compressed ('version/output') 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?

With an output schema present, the description does not need to enumerate return fields, and it correctly focuses on scope, parameter meaning, and how to use the result. The remaining gap is paging mechanics (page size, when to stop) for a canvas inventory that could be large.

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 the burden and mostly does: output_id is explained as selecting a clip/format, and element_offset as paging through the canvas inventory. video_id's ownership constraint is stated ('an owned video'), though the page size or default for element_offset is not given.

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 with concrete scope: version, scenes, captions, and editable canvas element IDs/capabilities for an owned video. It implicitly distinguishes itself from mutation siblings by pointing at set_element_content and set_element_layout as consumers of its output, though it never explicitly contrasts with read siblings like list_versions or check_video.

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

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

It gives a clear downstream-use pattern (feed the returned version/output, IDs, and capabilities directly into the direct-edit tools without a second model round), which implies when to reach for this tool. However, there are no explicit when-not-to-use conditions or a named read alternative (e.g., list_versions for version history, check_video for validation), leaving the agent to infer 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 establish the safe, idempotent, closed-world read profile, and the description adds real context on top: deterministic ordering (oldest first), an inventory of the fields returned (who asked, status, resulting version), and an explicit cost statement (free, no credits). It does not mention pagination or result-size limits, 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?

A single front-loaded sentence carries the scope, ordering, and returned fields, followed by a short cost tag. It is dense but every clause earns its place; the enumerative run-on is the only mild readability cost.

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-only tool with an output schema, annotations, and full schema coverage, the description supplies what structured data cannot: ordering, field inventory, and cost. The remaining gap is routing guidance against sibling history/activity 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?

With a single parameter and 100% schema description coverage, the schema fully documents video_id and its provenance from list_videos. The description contributes nothing parameter-specific, so this is the baseline 3.

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

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

States a specific verb (read) and resource (a video's history) and enumerates what the thread contains: rounds of changes, direct edits, caption fixes, authors, statuses, versions. It does not, however, distinguish itself from nearby siblings such as get_video_activity or list_versions, which an agent may plausibly confound.

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

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

There is no when-to-use guidance: no statement of the situation that calls for the thread versus get_video_activity, check_video, or list_versions. The only usable cue is the free-cost note, which is a preference signal rather than a usage rule.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral facts beyond those: it only applies 'while a video is being made' and it is free ('Cost: Free: no credits'), which is exactly the kind of cost/auth context annotations cannot express. It stops short of describing polling cadence or what happens after completion.

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

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

Three short sentences, front-loaded with the triggering condition and core action before the field list, usage advice, and cost note. Every sentence earns its place, though 'Cost: Free: no credits' has redundant phrasing that could be tightened.

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 an output schema present the description need not explain return values — yet it still previews them usefully — and annotations carry the safety profile. Between the timing constraint ('while a video is being made'), the narration guidance, and the cost note, an agent has everything needed to call this correctly during a render.

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

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

There is a single parameter (video_id) and schema description coverage is 100%, so the schema already documents it fully as 'The video id from list_videos.' The description mentions no parameters at all, so the baseline of 3 applies — the schema does all the parameter work.

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

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

States a specific verb and resource ('read what the editor is doing') and enumerates the returned fields (stage, minutes left, paper edit, steps, names heard), which is far more concrete than a tautology. It does not, however, explicitly distinguish itself from closely related siblings such as check_video or list_videos, so it lands at clear-but-undifferentiated rather than a full 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 a clear when-to-use rule: 'Use it to narrate progress instead of waiting silently,' which frames it as a polling/narration tool during an in-flight render. It supplies no exclusions or named alternatives (e.g., what to call once the video is finished, or how it differs from check_video), so it is strong context without the full when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description restates 'Read-only' (no added credit) and adds only 'free', a minor cost signal. It doesn't disclose return shape beyond the topic list, but with annotations and an output schema present, a 3 is fair.

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

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

Front-loaded with what the tool is, then the topics, then the usage discriminator, with no filler. Slightly dense in the middle clause, but 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 zero-required-parameter docs-retrieval tool with annotations and an output schema, the description covers purpose, the option space, and when to invoke. Nothing essential is missing, though it could note the default topic behavior explicitly.

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 the parameter, and it does: it names all six enum values for 'topic' and glosses what several contain ('which tool and fields for a request', 'changes and the canvas', 'posting and monthly plans'). That adds real meaning beyond the bare enum in the schema.

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

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

The description makes clear this tool returns extended guidance notes on Clypmint and enumerates the six topic areas (overview, music, styles, editing, publishing, capabilities), so the resource is unambiguous. The verb is only implied ('Fuller notes on using Clypmint') rather than stated, and the name/title ('get_workflow' / 'Read current Clypmint workflows') is arguably more precise than the body, but the purpose is still identifiable.

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

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

It gives an explicit when-to-use ('when a request is unusual') and an explicit when-not ('A normal request needs none of it: the tool descriptions are enough'). That is a genuinely discriminating routing rule an agent can apply without inspecting siblings.

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

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

Goes well beyond the annotations by disclosing the 32 MiB cap, the seven-day lifetime of the staging key, and the idempotency mechanism (same operation_id and file returns the original receipt). Annotations already flag idempotentHint and openWorldHint, so the added expiry and size limits are the real value; rate limits and permission requirements go unmentioned.

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 size limit, then the input-path branching. Slightly dense in a single paragraph, and the closing Brand-page URL is a mild tangent, though it serves a real dead-end case.

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

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

Covers the input modes, the size ceiling, logo semantics, the return value's downstream use (asset_staging_keys on create_video), and its expiry. With an output schema present and 80% param coverage, nothing an agent needs to call this correctly is missing.

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

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

With 80% schema coverage the baseline is 3, but the description adds genuine meaning: it explains when to prefer url over file, that logo:true designates the brand mark, and what operation_id buys (idempotent replay). Only the file_name parameter gets no added explanation.

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 (import), the exact resource (one image or song up to 32 MiB), and immediately names what it is not: "Does not import video footage (edit_video does)." An agent can distinguish it from list_assets and edit_video 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?

Explicitly routes between the two input paths: file for attachments in ChatGPT, url "from Claude or any host that cannot attach files." It names the exclusion (no video footage; edit_video does that) and gives a fallback for the no-link no-attachment case via the Brand page.

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, closed-world, and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context with the ownership constraint (only assets belonging to the linked account) and the fact that the returned IDs are the ones video creation accepts. Pagination/ordering behavior is not mentioned.

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 well-formed sentence with no filler, front-loading the primary action and scope, and ending on the detail that makes the output actionable.

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

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

For a zero-parameter read tool with rich annotations and an output schema describing the returned assets, the description covers identity, scope, and downstream use. It omits only minor operational detail such as result limits or ordering.

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, which sets the baseline at 4. The description correctly implies no filtering or selection arguments are needed, and the schema already carries 100% coverage.

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

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

The description uses a specific verb+resource ("List reusable media") and adds scope ("owned by the linked account") plus the downstream purpose ("asset IDs accepted by video creation"). It clearly separates this from write-oriented siblings like import_asset, but never names a sibling explicitly.

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

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

Usage is only implied: an agent infers it should call this to discover asset IDs before video creation, since the description ties the output to that workflow. There is no explicit when-to-use, when-not, or named alternative such as list_videos.

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 closed-world behavior, so the safety profile is covered. The description's only additive behavioral detail is billing context ("Cost: Free: no credits"), which is genuinely useful but thin; nothing is said about scoping, defaults, or result size.

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 compact sentence with no filler, and the resource being listed is front-loaded. It is slightly dense and run-on (resource, forget linkage, and cost packed together), but nothing is wasted.

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

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

For a simple read-only list tool this covers the essentials: what is listed, the relationship to forget, and the fact that it is free. An output schema exists so return values need not be described, though the optional brand_id default remains unexplained.

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 description never explains brand_id — it only obliquely implies the listing is "for the brand". Since brand_id is optional (0 required), an agent gets no help on what happens when it is omitted, and the format/pattern details are left entirely to the schema.

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

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

States a specific verb ("List") and a concrete resource ("the preferences, looks and spellings Clypmint remembers for the brand"), which is far more informative than the tautological title. It also links to the forget sibling via "the ids forget takes", helping distinguish it from remember/forget, though it never states how it differs from remember directly.

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?

"with the ids forget takes" implies the intended workflow (list to obtain ids, then forget), which is real, if implicit, usage guidance. It does not explicitly say when to prefer this over remember or any other sibling, nor does it address the optional brand_id case, so guidance stays at the implied level.

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/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond them: result ordering (newest last), inclusion of the live-version indicator, and the free/no-credit cost. It doesn't discuss pagination, though an output schema exists to cover the shape.

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

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

Three short clauses, front-loaded with purpose and ordering, then workflow pairing, then cost. No filler sentences; each 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 single-parameter read-only list tool with an output schema, the description covers what an agent needs: what it returns (versions, newest last, live flag), how it relates to restore_version, and that it costs nothing. Nothing material is missing.

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

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

Schema description coverage is 100% and the single required video_id is documented there ('The video id from list_videos'). The description adds no syntax or format detail beyond the schema, so the baseline 3 for schema-carried parameters is appropriate.

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

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

States a specific verb (List) and resource (versions of a video), plus distinguishing output facts — ordering (newest last) and which version is live. It also names the sibling it pairs with (restore_version), so an agent can place it without reading 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?

Explicitly ties the tool to restore_version for undoing changes, giving a clear workflow context. It stops short of stating when-not-to-use or naming other alternatives, but the intended use is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description usefully adds the hard cap of 20 results and recency ordering, but says nothing about pagination or how to retrieve anything beyond those 20, which matters for a list 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?

A single sentence with zero filler, front-loading the result cap and recency ordering before the account scope. Every clause earns its place.

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

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

An output schema exists, so return values need no explanation, and the zero-param schema needs no parameter prose. The description covers scope, ordering and cap; the only gap is whether the 20-result limit is a hard ceiling or paginated.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool is 4. The description correctly implies the tool is unfiltered and unscoped by input.

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

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

States a specific verb (list) and resource (videos), plus meaningful scope: 'up to 20 recent' and 'in the linked Clypmint account'. It does not differentiate itself from siblings like list_assets, list_posts, list_versions, or check_video, 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?

There is no when-to-use guidance, no when-not-to-use, and no mention of alternatives such as check_video or get_video_activity. The only implicit signal is that it returns 'recent' videos, which is weak routing information among so many sibling tools.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is known. The description usefully adds the quota basis ('direct-edit allowance'), cost, refusal behavior for unsupported changes, and the retry/idempotency rule, but it does not state how prior bounds are affected or whether the change can be undone.

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 effect, followed by short operational notes in rough dependency order (precondition, save behavior, refusal, retry, quota/cost). Slightly dense with operational boilerplate, but every sentence carries usable 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?

Output schema and annotations cover return values and safety, and the description fills in prerequisite workflow, payability of the result, refusal semantics, and a follow-up path ('check_video with_download'). Only the precise meaning of 'refuse without rebuilding' and irreversibility of bounds changes remain unstated.

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 all six parameters are already documented, including operation_id retry semantics. The description adds workflow provenance for base_version/output_id, but its claim that output_id comes from get_project_context mildly diverges from the schema's 'one output from check_video', so it does not clearly exceed 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 ('Set the scene's first and last transcript word numbers') and immediately clarifies the effect ('shorten a graphic without removing the footage underneath'), which distinguishes it from remove_scene and cut_video_words. An agent reading only this line knows what changes and what is preserved.

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

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

Gives explicit sequencing ('Read get_project_context first and pass its base_version and selected output_id') and a clear use case. It doesn't name a sibling alternative (e.g. cut_video_words) for when the underlying footage should also go, so a small routing gap remains.

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

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

Discloses important behavior beyond the annotations: the call may be long-running, may tell the agent to retry with the same operation_id, makes no videos and spends no credits, and returns plan_id, ideas, and a quote. It also states the cost model for later video creation, which an agent needs before recommending approval.

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

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

The description is dense but front-loaded with the main purpose and key constraints. Every sentence adds useful procedural or cost context, though the long parenthetical-heavy prose could be more scannable for a tool with this many parameters.

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 13-parameter planning tool, the description covers the critical call behavior, output values, cost, and approval workflow, and an output schema exists for return details. The remaining gap is that several optional parameters are not explained in the description and are only partially covered by the schema.

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

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

The description explains the core parameters (topic, days, count, items) and the item shape, and clarifies that supplied items are taken as written at once. However, with 13 parameters and only 62% schema description coverage, it leaves several optional parameters such as seconds, audience, style_id, timezone, and instructions unexplained in the description. The schema carries part of the burden, so a baseline 3 is appropriate.

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

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

States a specific verb and resource ('Start a content calendar for a topic') plus the exact output shape: video ideas with title, hook, script, caption, hashtags, and posting time. It names the relevant downstream siblings edit_content_plan and approve_plan, so the agent can distinguish this from editing or approving a 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?

Gives explicit trigger phrases ('start a faceless account', 'a month of posts about X') and explains the two modes: send self-written items versus let Clypmint write them. It also prescribes the post-call workflow: show the ideas to the user, use edit_content_plan for changes, and call approve_plan only after the user agrees.

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, and the description adds substantive context beyond them: the edit persists as a playable project, unsupported changes are refused without partial rebuilds, operation_id must be preserved on retries, the call consumes the account's direct-edit allowance, and it costs no credits. The only gap is not spelling out what an 'update' does to unlisted properties of an existing overlay.

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

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

Purpose and allowed kinds are front-loaded, then prerequisites, persistence semantics, failure behavior, retry rules, and cost in a tight sequence of short sentences. Slightly telegraphic phrasing ('Cost: Free: no credits') is dense but each sentence carries distinct information, so little is wasted.

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

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

For a destructive, version-guarded mutation with an output schema present, the description covers everything an agent needs before calling: required prior tool, ID sources, concurrency token, idempotent retry protocol, refused-change behavior, and quota/cost. Return-value details are correctly omitted since an output schema exists.

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

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

Schema coverage is 80% and four parameters already carry descriptions, so the baseline is 3. The description goes above that by explaining the overlay kinds (text/image/video) that drive the untyped oneOf and their animation enum, and by tying base_version/output_id to get_project_context so the agent knows where those values come from.

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+scope: 'Add or update one timed text, image or video overlay', and enumerates the animation types. An agent can distinguish this from remove_video_overlay by the verb, but no sibling is named explicitly, so differentiation is implicit rather than stated.

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

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

Gives explicit prerequisites ('Read get_project_context first and pass its base_version and selected output_id'), constrains inputs ('Use only existing canvas asset IDs and editable capabilities returned by the project'), and routes elsewhere for the follow-on need ('request a file separately with check_video with_download'). This is clear when-to-use and when-to-use-something-else guidance.

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

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

Annotations declare destructiveHint=true, idempotentHint=true and openWorldHint=false, but the description never explains what is destroyed (e.g., whether a new preference overwrites an existing one) or why a "remember" action is marked destructive. The cost line ("Free: no credits") is the only behavioral addition, and the 200-character limit merely repeats the schema's maxLength.

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 and the sentence is reasonably compact, but the trailing "Free. Cost: Free: no credits." is redundant self-repetition that adds no information. The character-limit clause duplicates the schema constraint rather than earning 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?

An output schema exists, so return values need not be explained, and the core operation is understandable. However, for a mutation tool flagged destructive, the missing overwrite/idempotency semantics and the undocumented brand_id leave real gaps for correct invocation.

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

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

Schema coverage is only 50%: text is documented in the schema, and the description's "plain words" plus examples largely duplicate that. The brand_id parameter has no description anywhere, and the description does not clarify whether it defaults to the current brand, which is exactly the gap a description should fill.

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?

"Teach Clypmint one lasting preference for every later video of this brand" gives a specific verb (teach/store), resource (preference, scoped to a brand), and scope (applies to later videos). The examples of preference types (caption size, pace, name spelling) make the intent unambiguous. It does not name its siblings (forget, list_memory), so an agent must infer which one removes or lists preferences.

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: call this when you want to persist a durable brand-level preference rather than a one-off edit. There is no explicit guidance on when not to use it, no mention of the forget/list_memory alternatives, and no statement about whether brand_id is required or what happens when it is omitted.

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: it discloses that footage time is destroyed, that the result is a saved playable project rather than a file, that unsupported changes refuse without rebuilding, that operation_id and exact inputs must be preserved on retries, that it consumes the account's direct-edit allowance, and that it costs no credits.

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 each sentence carries operational value (alternative, prerequisite, output, failure mode, retry, quota, cost). It is dense and slightly crammed into one paragraph, but there is no filler.

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

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

For a destructive mutation with an output schema and annotations already covering safety, the description supplies everything else an agent needs: prerequisite call ordering, version pinning, idempotent retry protocol, quota/cost impact, and failure behavior.

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

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

Schema coverage is already 100%, so baseline is 3; the description adds cross-tool provenance for base_version/output_id and stresses retry semantics for operation_id. Slight ambiguity: it says output_id comes from get_project_context while the schema attributes it to check_video, which could confuse a careful agent but is not harmful.

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 ("Remove this scene and its footage time") and immediately names the closest sibling (remove_scene_layer) with the distinction between full-scene removal and layer-only removal. An agent can differentiate it from add_scene/move_scene without inspecting any schema.

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

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

Gives explicit when-to-use vs. alternative ("To remove only graphics or camera motion while keeping speech, use remove_scene_layer"), plus a mandatory prerequisite sequence (read get_project_context first, pass base_version and output_id) and follow-up routing (request a file via check_video with_download).

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 destructive/idempotent, but the description adds substantially: unsupported changes refuse rather than rebuild, a playable project is saved while file export is a separate step, operation_id must be preserved on retries, and the call draws on the account's direct-edit allowance at no credit cost. These are non-obvious operational traits an agent cannot infer from the schema or 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 action and its preservation guarantee, then supporting operational detail in short clauses. Dense and largely telegraphic, but virtually every sentence carries a distinct constraint; only the trailing cost sentence is close to boilerplate.

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 an output schema handling return shape and annotations covering safety, the description fills the remaining gaps: prerequisites, version pinning, refusal behavior, retry identity, export path, and cost. Nothing needed 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 83%, so the schema already documents all six parameters including the layer enum. The description still adds value by tying base_version and output_id to get_project_context/check_video and by explaining retry semantics for operation_id.

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

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

States a specific verb and resource ('Remove the graphic or camera movement from this scene') and immediately scopes it ('preserving its footage and captions'), which distinguishes it from remove_scene and add_scene without the agent opening any schema.

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

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

Gives a clear prerequisite ('Read get_project_context first and pass its base_version and selected output_id') and routes file retrieval to check_video with_download. It does not explicitly name remove_scene as the alternative when the entire scene should go, so the exclusion is only implied.

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

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

Annotations already flag destructiveHint/idempotentHint, and the description adds real context: underlying footage is preserved, a playable project is saved, unsupported changes are refused without rebuilding, the account's direct-edit allowance is consumed, and the call is free. That is meaningful disclosure beyond the structured safety flags.

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 outcome, and every clause carries operational value (cost, refusals, retries). The telegraphic fragments ('Cost: Free: no credits.') are efficient but slightly clipped in style.

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 an output schema, return values need not be explained; the description instead covers what an agent actually needs — prerequisites, versioning, side effects, refusal behavior, retry semantics, and cost. Nothing essential 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?

With 80% schema coverage the baseline is 3, and the description adds provenance: base_version and output_id come from get_project_context, and operation_id must be stable across retries. Minor friction in that the schema says output_id comes from check_video while the description points at get_project_context.

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 ('Remove one added overlay by its returned ov_ ID') plus the resulting state ('preserving underlying footage'), which cleanly separates it from put_video_overlay and remove_scene. The ID-pattern reference makes the target unambiguous.

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

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

Explicitly prescribes the prerequisite sequence ('Read get_project_context first and pass its base_version and selected output_id') and routes to siblings for adjacent needs ('request a file separately with check_video with_download'). Retry guidance ('Preserve operation_id and exact inputs on retries') covers the main misuse case.

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

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

Beyond annotations, the description discloses important behavior: saving a playable project, refusal of unsupported changes without rebuilding, retry/idempotency handling via operation_id, use of the account's direct-edit allowance, and that the operation is free. These details materially help an agent call it correctly.

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

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

The description is front-loaded with the core action and then adds only operationally relevant details: prerequisites, project saving, refusal behavior, retries, allowance, and cost. Each sentence carries useful information with 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?

Given the 100% schema coverage, output schema, and destructive/idempotent annotations, the description covers the key prerequisites, side effects, retry behavior, cost, and separate file retrieval. An agent has enough context 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 100%, so the baseline is 3, but the description adds workflow meaning by tying base_version and output_id to get_project_context and by reinforcing operation_id preservation on retries. It does not add much about the nested screen object, but the schema already documents that.

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: replacing a scene screen with the supported screen shape from get_project_context. It is clear enough for an agent to identify the operation, though it does not explicitly distinguish it from nearby tools such as swap_scene_picture or add_scene.

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

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

It gives clear workflow guidance: read get_project_context first, pass base_version and selected output_id, and use check_video with_download to request a file separately. It also notes that unsupported changes are refused, but it does not explicitly compare this tool against sibling editing tools beyond the download alternative.

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

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

Adds real behavioral context beyond the annotations: it clarifies the undo semantics, that nothing is deleted, and that the call costs no credits. The 'nothing is deleted' note usefully scopes the destructiveHint=true annotation rather than contradicting it (the live version is still superseded). It does not say what happens to the currently live version, which is the one 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?

The purpose clause is well front-loaded, but the tail is padded and garbled: 'Free. Cost: Free: no credits.' says the same thing twice in an awkward fragment. One of those sentences does not earn 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 simple two-parameter mutation with a 100%-covered schema and an output schema, the description covers the essentials: what it does, that it is non-deleting, and that it is free. Only the effect on the previously live version is unstated.

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

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

Schema description coverage is 100%, and both parameters are already documented in the schema (video_id from list_videos, version_id from list_versions). The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Make an earlier version of a video live again (undo)'. This is unmistakably distinct from siblings like list_versions or edit_video, so an agent can select it without opening the schema.

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

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