aicut

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

Goes well beyond the annotations: async/no-wait behavior, typical and worst-case latency, zero token cost versus a daily per-account allowance with `daily_limit_exceeded` handling, no-loop guidance, and idempotency-key replay semantics. The 'generates nothing' statement is consistent with readOnlyHint=false (it still creates an analysis job) and idempotentHint=false (new jobs on repeat calls).

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 contract and organized into labeled sections (WHEN, WHICH VIDEOS, AFTER, TIMING, COST, IDEMPOTENCY), which is easy to scan. It is dense and somewhat repetitive in the COST sentence ('nothing to confirm about cost and no reason to check the balance'), which 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?

For an async job-creating tool with no output schema, the description supplies the return value (analysis id), the follow-up polling tool and interval, terminal statuses, latency expectations, and failure semantics. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds real meaning: the 128-second window cap and 'cover a long video with successive windows' for the start/end pair, and 'never reuse one for a new generation' for the idempotency key. It stops short of restating per-parameter syntax, which the schema already handles.

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

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

The opening sentence states a specific verb and resource ('starts an AI analysis of an existing video') plus the async contract ('returns the new analysis's id immediately, does NOT wait'). It further specifies the output content (description text, on-screen text, pacing, platform metadata) and explicitly separates itself from `generate_video`.

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

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

Explicit WHEN clause, explicit WHICH VIDEOS acceptance/rejection rules with 'do not retry it in a different form', an AFTER section routing to `get_analysis` with a polling interval, and a WHEN-NOT for generation via `generate_video`. The agent has everything needed to choose this tool and to sequence follow-up calls.

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/closed-world, yet the description adds genuinely non-obvious behavior: it costs nothing, the card self-loads the catalogue, the user's pick arrives as a chat message from the user, the card stays live, and a later override message wins completely. That post-call protocol is not derivable from any structured field.

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

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

Front-loaded with the action, then WHEN NOT, AFTER, and OUTPUT in a scannable order, and nearly every clause carries operational content. It is nonetheless long for a zero-parameter tool, with heavy capitalization and several overlapping 'do not' prohibitions that could be compressed.

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-param, no-output-schema tool, an agent has everything it needs: trigger conditions, exclusions, the exact post-call message to send, what not to do afterwards, and how to handle late overrides. Nothing forces a follow-up call to disambiguate the flow.

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 the baseline is 4; there is nothing to disambiguate. The description does add an OUTPUT note ('one short object naming the catalogue, for the card') plus an instruction not to paste or summarise it, which is useful but not parameter semantics.

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

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

A concrete verb plus resource ('PUTS THE SERIES CATALOGUE ON SCREEN as a grid of previews') with what each tile does and what selecting one produces. It explicitly contrasts with `list_series`, so an agent can route between the two without opening either schema.

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

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

Gives a positive trigger ('the moment the user wants to make a story episode or asks what story formats exist and has not named one') and a WHEN NOT block with a named alternative and the exact condition (user named a series, asked about one series' details, or the client renders no cards). It even covers the recovery path if the user reports not seeing the picker.

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

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

The annotations already mark this as a destructive, non-read-only, non-idempotent operation, and the description adds substantial operational context beyond that. It discloses that the scene text changes even if image generation fails, that `changed_text: true` means the beat changed with only the old picture, that `changed_text_unknown: true` must not be resent immediately, and that `attached: false` means the image is charged but will not replace the frame at fire.

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

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

The description is long, but the complexity of the tool and its failure modes justify much of the length. It is front-loaded with purpose and restrictions, then organized into WHEN, AFTER, COST, GO, and IDEMPOTENCY sections; the all-caps emphasis is dense but most sentences carry operational value.

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

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

Although there is no output schema, the description covers the returned `image_id`, `changed`, `report`, and `attached` fields, plus the critical `changed_text: true` and `changed_text_unknown: true` outcomes. It also covers cost behavior, refusal behavior, the frames-review prerequisite, and retry safety, leaving little an agent needs to infer before calling it.

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

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

Schema description coverage is 100%, so the baseline would be 3, but the description adds meaningful interaction semantics beyond the schema. It clarifies that `change` must be visible rather than dialogue-only, that `scene_index` is zero-based against `story.frames` while users count from one, that `estimate_only` is best-effort and may return `utility_rate_limited`, and that `idempotency_key` keys only the picture while text is rewritten on every call.

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

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

The description states a specific verb and resource: it changes what happens in one scene and redraws that scene's opening picture. It explicitly distinguishes the tool from `regenerate_story_frame`, which redraws the same scene from the same text, so an agent can route correctly without opening another schema.

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

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

It gives explicit when-to-use conditions (`story.stage` is `frames_review`, one named scene, one priced ask) and names the alternative for same-text redraws. It also spells out refusal and mixed-ask cases: dialogue-only asks return `dialogue_only`, while mixed asks apply only the visible half and must be relayed accurately.

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

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

Goes well past the annotations: failure behavior (file refused, never added, nothing charged, re-encode to MP4/PNG/JPEG), cost ('no tokens'), return payload fields, and a concrete error-diagnosis path (bare '000' means storage host unreachable). The 'safe to call again' note sits alongside idempotentHint=false but is about safety/cost rather than state, so it reads as compatible context rather than a contradiction.

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

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

Purpose and WHEN are front-loaded and nearly every sentence carries operational weight (route-specific failure handling, retry rule, cost). It is dense and somewhat long for a one-parameter tool, and the closing 'AFTER THIS the url works as any input of its kind' partly restates the earlier return-value 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?

No output schema exists, and the description fully compensates by enumerating returned fields (url, size, kind, width/height, duration_seconds for video). Combined with failure semantics and retry cadence, 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 description coverage is 100% and the single `id` param is already documented as 'the id upload_media returned'. The description reinforces that provenance but adds no new syntax, format, or edge-case meaning beyond the schema, so the baseline of 3 applies.

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

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

Opens with a specific verb + resource: 'Checks the file uploaded to an upload_media target and makes it usable.' It explicitly ties itself to the sibling upload_media as the second half of a two-step flow, so an agent can distinguish confirming from uploading without inspecting either schema.

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

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

A dedicated WHEN clause states the exact trigger (curl printed 2xx, or user says the browser_upload_url page is done), plus retry timing ('wait a few seconds and call once more') and a negative rule ('DO NOT CALL upload_media AGAIN'). It also branches guidance by upload route (curl vs browser), which is exactly the decision an agent faces.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantial non-obvious behavior: no refund and why, forfeiture of a future refund when deleting a generating video, no trash and irreversibility, removal of the row but not the charge, and the 404 semantics ('it is not there' rather than 'belongs to someone else'). It also warns against prompt-injection-style authorization from tool output, which no structured field conveys.

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

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

Front-loaded with the verb and scope, then the WHEN, then consequences and safety rules — a sensible ordering. It is dense and somewhat long for a single-parameter tool, with a few ideas restated (irreversibility, refund), but nearly every sentence carries decision-relevant information.

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

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

For a destructive, irreversible mutation with one parameter, the description covers preconditions, refusal conditions, financial consequences, error interpretation, and irreversibility. No output schema exists, yet nothing an agent needs in order to call this safely is missing.

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

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

Schema coverage is 100%, so the `id` field is already documented as coming from `list_videos` or `generate_video`. The description adds real operational context beyond the schema: the host prompt shows the id rather than the title, so the agent must name the video in its own message before deleting.

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 with scope: 'Deletes ONE video from the signed-in account's library', explicitly covering any state (finished, failed, generating) and equating it to the web app's delete button. An agent can distinguish this from remove_story_scene or 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?

Gives an explicit WHEN (user asks to remove a video or tidy up after a failed one), an explicit case where deletion is unnecessary (a `writing_failed` story episode charged nothing and can be left), and a wait condition (if a running job might still fail). It also states a hard eligibility rule: the user must have asked THIS SESSION in their own words for this specific video.

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

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

Goes far past annotations: it discloses persistence into later episodes, the already-shown cast card and explicit no-polling rule, the `changed: []` meaning, the 402 case ('description already changed, old portrait'), and the 503 re-attach procedure with key semantics. Annotations only say destructive/openWorld; the description supplies the operational consequences.

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

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

Dense but front-loaded: purpose first, then WHEN, then constraints, then cost/idempotency. Some material (COST, GO, IDEMPOTENCY) restates server-wide spending rules, which is mildly redundant, but every block addresses a real failure mode.

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

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

With no output schema, the description must carry the return contract, and it does: new `description`, `portrait_image_id`, `portrait_status: "generating"`, `changed`, and the `report` relay instruction. Failure modes, cost, and idempotency are all covered for a destructive, paid mutation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds: the description parameter must be a whole standalone line (not a diff), ~500 char limit, and `estimate_only` prices without re-describing. `idempotency_key` replay behavior is also explained beyond the schema's terse note.

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 ('CHANGES ONE cast member into a different character') with a capsule of the mechanism (rewrites stored look, draws ONE portrait, roster untouched). It explicitly contrasts with `regenerate_cast_portrait` and `generate_cast`, so an agent can route correctly without opening schemas.

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

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

The 'WHEN' clause names the selecting intent ('the user wants a member to BE something else') and both wrong alternatives with their reasons. It also covers the free-draft edge case (no library ids, re-draft instead) and the pre-spend workflow.

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

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

Goes well beyond annotations: cost model (server-measured length × per-second rate × resolution), token-spend consent workflow, idempotency replay semantics ('REPLAYS the first job whatever the settings'), card/url fallback, and waiting behavior. No contradiction with destructiveHint=true or idempotentHint=false — the replay warning actually reinforces the non-idempotent claim.

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?

Telegraphic and front-loaded with labeled sections (WHEN, THE CARD, WAIT, COST, SPENDS TOKENS, IDEMPOTENCY), so it scans fast. It is dense and long — some cross-references to 'this server's instructions' consume space without adding local information, keeping it off a 5.

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

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

For a costly, destructive, open-world generation call with no output schema, the description covers prerequisites, consent/spend gating, waiting protocol, idempotency, return shape (job id, url fallback), and failure cases (other account's video refused, 3–10s limit). Nothing an agent needs is missing.

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

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

Schema coverage is 100% so the schema carries field-level meaning, but the description adds real usage guidance beyond it: how to price with `estimate_only: true`, that idempotency keys must never be reused, and that `720p` should be named in the priced ask. It does not repeat all params, which is correct.

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

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

Opens with a specific transformation ('the SAME clip with the prompt's changes applied') and pins the invariant ('camera, timing and motion stay'), which cleanly separates it from generate_video/extend_video/reshot_video siblings. An agent knows exactly what this produces 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 WHEN block with example utterances ('make it snow', 'put them in suits'), a prerequisite (read `get_recipe` `restyle` first), and a negative exclusion (do not call `show_generation` for this job). Follow-up protocol via `wait_for_generation` and the no-polling rule are spelled out.

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

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

Annotations only declare the safety profile (not read-only, destructive, open-world, not idempotent); the description adds the operational facts an agent actually needs: tokens are spent and priced off the new segment's model/duration/resolution, an external URL consumes one media-ingest slot (quote and create from the same URL), and a reused idempotency_key REPLAYS rather than creates. It also discloses that the card was already opened and specifies a wait protocol, none of which is inferable from the annotations.

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

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

Front-loaded correctly: purpose and return value in sentence one, then WHEN, card, wait, cost, tokens, idempotency in labeled blocks that are easy to scan. Some bloat remains in capitalized imperatives and the split COST / SPENDS TOKENS sections, and phrases like "again at once while `terminal: false`" are compressed to the point of ambiguity.

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 costly, open-world, non-idempotent mutation with 9 params and no output schema, the description covers every decision the agent must make: model discovery, pricing and approval protocol, URL ingestion cost, idempotency hazard, UI card state, wait protocol and the no-card fallback of handing over the URL.

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

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

Schema coverage is 100% and several param notes are near-duplicates of the schema (duration as NEW segment length, aspect_ratio not guessed). But the description adds constraint-level meaning the schema lacks: `model` must be one that can start from an image, `prompt` should describe what happens NEXT or you get a repeat of the source, and the same-URL ingest-slot rule spans two parameters.

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

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

First sentence gives a specific verb, resource and distinctive mechanism: generates a NEW segment continuing from the video's final frame, returns the job id immediately, and the result is the source clip with the segment joined on. That last clause cleanly separates it from generate_video, edit_video and reshot_video without naming them.

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

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

An explicit WHEN clause names the user intents that trigger it (extend, continue, lengthen, "what happens next"), plus prerequisites (call list_models first; only image-start models accepted) and an explicit prohibition (do not call show_generation for this job). It also routes post-call behavior to wait_for_generation and away from get_* polling, which is real alternative-selection guidance.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, but the description adds substantial operational context: irreversibility and no refunds, largest single charge, 409 `already_fired` means the first fire worked, `scenes_price_unavailable` means finish in the web editor, and the card should not be polled. It also discloses timing, token-spend behavior, and the fact that `idempotency_key` is ignored because the consumed gate is the guard.

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 uses headings for WHEN, THE GO, THE CARD, TIMING, COST, and FIRE ONCE, which makes a complex destructive workflow easy to scan. It is lengthy and repeats timing and price cautions in multiple sections, but most of that repetition serves the high-stakes irreversible charge.

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

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

There is no output schema, but the description supplies the relevant outcome states (`fired: true`, `story.stage` `generating_scenes`, `ready_to_render`), the next tool to call, error handling for 409s, and the no-polling card behavior. Given the destructive annotations and the 100% schema coverage, the definition is complete enough for an agent to invoke it safely.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful meaning beyond the schema for `estimate_only` by specifying it must be first and that its quote includes `scene_count` and `duration_seconds`, and for `auto_render` by tying it to approval of the render charge. It also reinforces that `idempotency_key` is ignored and that a repeat fire returns 409. It does not add much beyond the schema for `video_id`.

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

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

The description opens with a specific verb and resource: FIRES a parked AI Video Story episode, stage 2 of 3, generating every kept scene's video from its reviewed picture. It clearly distinguishes this from sibling tools like render_story_video, regenerate_story_frame, and remove_story_scene by naming their roles and sequencing.

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

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

It states the exact trigger condition (`story.stage` is `frames_review`), the required prerequisite of cutting scenes first, and the need to quote with `estimate_only: true` before firing. It also lists explicit non-triggers, including scene cuts, redraws, picture approval, and price questions, and tells the agent to ask rather than fire when in doubt.

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

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

The description discloses behavior beyond the annotations: async job-id return, up-to-four-minute timing, pricing model, estimate-only spending rules, idempotency-key replay semantics, and the fact that the call creates a card. These details are critical for a costly, destructive, open-world generation tool. The annotations do not contradict the description; `destructiveHint: true` is consistent with spending tokens and creating an audio asset.

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

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

The description is long but well organized with front-loaded labels such as WHEN, HOW IT SOUNDS, THE CARD, WAIT, TIMING, COST, and IDEMPOTENCY. There is some repetition around not spawning timers or background shells and around 'only if the user asked', but overall the length is justified by the 21-parameter complexity.

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 a 21-parameter generation tool with no output schema, the description covers the full operational picture: async behavior, model-dependent inputs, voice sourcing, waiting behavior, pricing and estimates, spending rules, and idempotency. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is already 100%, so the schema carries the field-level semantics. The description still adds cross-parameter meaning that the schema cannot express: model-specific arguments, the rejection of fields a model does not publish, voice-id sourcing, and the Lyrics-vs-Quick mode distinction. It does not add much syntax beyond what the schema says, which keeps it below 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?

The description states a specific verb and resource: starts an audio generation on the signed-in aicut account and returns a job id immediately. It also distinguishes the four supported audio subtypes (speech, music, song, sound effect) by the `model` parameter, which is enough to tell it apart from siblings like `generate_video` or `wait_for_generation`.

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 WHEN criteria and named prerequisites (`list_models`, `get_recipe`, `list_voices`) before calling. It also routes the agent to `wait_for_generation` after the call and explains not to use `show_generation` for this job, which is exactly the alternative-selection guidance needed.

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?

Without annotations this would be near-perfect: it discloses that the call is free, persists nothing, produces a redeemable `draft_id` for roughly two hours, and documents the exact 400 `invalid_request` and 429 `utility_rate_limited` recovery paths. However, the annotations already declare openWorldHint=true and destructiveHint=false, and the description's "saves nothing" claim sits uneasily beside readOnlyHint=false (a draft object with an id is created), so a small part of its behavioral framing is redundant rather than additive relative to the structured fields. The remaining cost/error/expiry context is genuinely beyond annotations, lifting it to a 3 rather than higher given the overlap.

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 free/no-permission facts are front-loaded, and nearly every sentence carries actionable content (costs, ordering, error recovery, pricing fields). It is still a very dense single block of roughly 300+ words with shouted inline section markers (WHEN, WHAT IT RUNS, AFTER, WEBAPP-ONLY) inside one paragraph, which costs some scannability for a four-parameter tool.

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

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

There is no output schema, and the description compensates fully: it enumerates the response fields an agent must act on (`draft_id`, `idea` echo, `portraits_needed`, `portrait_models` with `per_portrait_tokens` and `total_tokens`) and warns against recomputing them. Combined with the next-step routing, expiry window, and error-code handling, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema; the baseline is therefore 3. The description adds real but partial value beyond it: the no-`idea` fallback behavior (an authored logline the user has not seen, which must be shown back) and the instruction to reuse the same `language` in `generate_story_video`. It adds nothing for `world` beyond what the schema states.

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 ("Writes the CAST for an AI Video Story series") with a concrete definition of the artifact (named characters with a role and one-line description) and its modality (DRAFT). It also explicitly bounds what it is not ("IT DOES NOT WRITE THE STORY") and routes to the sibling `generate_cast_portraits`, so an agent can distinguish it from neighbors 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 an explicit WHEN trigger (after the episode idea is settled, on a series with `cast.required` true), an explicit prohibition ("Never call it for a `cast.writer_owned` series"), and an explicit no-confirmation rule ("Do NOT ask permission"). It also names alternatives and the escalation path: re-draft with a sharper `idea` instead of buying portraits, and `describe_cast_member` for post-portrait edits.

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/not-idempotent/openWorld, and the description builds on that with real behavioral context: async generation, per-member charging, partial-charge semantics on 402 (`partial_cast`, `portraits_minted`, `charged_tokens`), the spent-draft 404/201-zero behavior on retry, and the null-`portrait_image_id` non-charge case. This far exceeds what annotations convey and is fully consistent with them.

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

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

Purpose is front-loaded and the dense text is largely earned given the billing and partial-failure complexity. It is long and reads as a wall of caps-laden instructions, with some redundancy (the 'never nothing was charged' point restated), but almost every sentence carries operationally necessary information for a paid, destructive tool.

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

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

With no output schema and a complex, paid, async, destructive operation, the description covers all an agent needs: return-state semantics (`portrait_status`, null ids, `charged_tokens`), card vs terminal polling, retry/idempotency behavior, and error codes. Nothing essential is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description adds meaning beyond the schema by explaining that `estimate_only: true` re-prices against the CURRENT catalog and by giving the OFFER-THE-IMAGE-MODEL protocol for `portrait_model` (default if no preference). These sharpen invocation but do not add syntax/format detail the schema lacks.

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 ('BUYS the portraits for a cast draft'), the per-member scope, the pricing basis, and the side effect of saving to the character library. It clearly distinguishes itself from generate_cast (reads the draft) and regenerate_cast_portrait (fixes one face), both named 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?

Explicit WHEN precondition (draft read, accepted, user said go to the price), an explicit exclusion from poll/show_generation, and named alternatives for each failure mode: regenerate_cast_portrait for one wrong face, describe_cast_member for a wrong character, fresh generate_cast for a new cast. Nothing is left to inference.

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

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

Annotations only say readOnlyHint=false and destructiveHint=true; the description supplies the real behavioral burden — per-character cost in two charged parts, the ElevenLabs ~4x premium, the 6000-character dialogue cap with no auto-cut, the start_confirmed:false recovery path (do not re-create, watch it), and the idempotency_key replay semantics. These are exactly the failure modes an agent needs before spending.

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?

Structure is front-loaded and logical: what it makes, who writes the script, what happens after, cost, exclusions, spending gate, idempotency. It is long and repeats the cost warning in both the description and voice_provider_left, and heavy ALL-CAPS shouting costs some readability, but for a 15-parameter token-spending tool nearly every sentence carries load.

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 full lifecycle despite having no output schema: it states the response carries the price split and renders_automatically:true, that wait_for_generation is the wait step, and that get_video yields the file url. Combined with the cost gate, size limit and unoffered-features list, an agent has everything needed to call it safely.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond by linking parameters across fields — changing voice_provider_* invalidates an older estimate, a longer script costs more, and estimate_only:true must be run before quoting. It does not restate per-parameter syntax, which the schema already owns, so it stays additive rather than redundant.

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

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

Opens with a specific verb and a precise artifact: 'CREATES a fake-text video: a phone chat conversation that types itself out over a gameplay or green-screen background, every line read aloud.' That is distinguishable at a glance from generate_story_video, generate_image_story and generate_audio 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?

Names the routing cases explicitly: 'YOU WRITE THE SCRIPT: there is no writer behind this endpoint,' show it as plain text first because 'iterating costs nothing', then 'one call makes the finished video ... no fire or render step' (ruling out fire_story_video/render_story_video), plus wait_for_generation and get_video for the terminal url. It also lists an explicit NOT OFFERED set (music, gameplay clips, in-chat images, contact photos, promotions, second chat, cantina skin) so the agent knows what to refuse rather than approximate.

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?

Despite annotations already covering mutation/open-world status, the description adds substantial behavior: immediate job-id return, card side effect, wait protocol, 1–3 minute timing, token spend, 409 revision-changed handling, and idempotency-key replay semantics.

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

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

It is dense but front-loaded and deliberately structured with WHEN, THE CARD, WAIT, TIMING, COST, SPENDS TOKENS, and IDEMPOTENCY labels. For an 11-parameter costly generation tool, every section carries operational value.

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

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

The description covers the full operational flow: preconditions, card behavior, asynchronous return, waiting rules, cost confirmation, revision conflicts, and idempotency. With no output schema, it still gives enough return-context by naming the job id and url fallback.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful mapping semantics (slug/revision come from the niche, values answer inputs by key, media fills image inputs, omitted settings use defaults), but most field-level detail is already 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 opening sentence states a specific verb and resource: run one niche, start a video, show the aicut card, and return the new job id immediately. It also explicitly states it does NOT wait, which distinguishes it from wait/polling siblings.

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

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

It gives explicit WHEN guidance tied to `list_niches`, tells the agent to read the niche first, and routes follow-up behavior to `wait_for_generation` while forbidding `show_generation` and `get_*` polling for this flow. Alternatives and exclusions are both present.

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: the ~24 second server-side wait and the fact a `url` is usually returned directly, the 90s–4min timing envelope, that tokens are spent and must be priced with `estimate_only: true` and consented to, and that a reused `idempotency_key` REPLAYS the first job regardless of settings. The destructive/openWorld/no-idempotency hints are all corroborated rather than contradicted, and the money-spend and idempotency-replay hazards are the exact context an agent needs.

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

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

Front-loaded with the verb, resource, and the ~24s wait behavior, and the labeled sections (WHEN, CONSENT, AFTER, THE CARD, WAIT, TIMING, COST) make it scannable. It is long for a tool description and has mild redundancy — "COST: this spends the user's tokens" is immediately restated by "SPENDS TOKENS," and the 24-second wait is repeated in TIMING — but the density is defensible for a costly, multi-param, card-managing operation.

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

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

With no output schema, the description supplies the return contract itself: `url`, `id`, and the `succeeded`/`queued`/`processing` status states plus what to do for each. For a 9-parameter, token-spending, destructive operation it also covers consent, cost, timing, and card state, leaving nothing an agent needs in order to call it and follow up 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; the description still earns a bump by explaining the batch `wait: false` pattern, that `model` must come from `list_models` (never a cheaper one), and the crucial replay semantics of `idempotency_key` that the schema only gestures at as "Retry-safety key." It does not add syntax detail for `resolution`/`quality`/`aspect_ratio` beyond what the schema already says.

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 ("Generates an AI image on the signed-in aicut account") plus the immediate user-visible side effect (the card is opened). It explicitly distinguishes this from the sibling it interacts with ("do not call `show_generation` for this job") and from `wait_for_generation`, so an agent can route correctly without opening other schemas.

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

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

WHEN is stated (user asks for an image), with the prerequisite chain (`list_models` first, `get_recipe` starter-image) and the consent exclusion (real person only with permission, never a public figure). The AFTER/WAIT sections tell the agent exactly what to do for `succeeded` vs `queued`/`processing` and forbid `get_*` polling, timers, and background shells — explicit when/when-not with named alternatives.

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 mark this destructive/idempotent=false, and the description backs that up with concrete spend semantics (price levers, what each lever does to image count), the idempotency replay hazard, translation/character-limit refusal behaviour, and the start_confirmed:false recovery rule. It also discloses that this single call renders the video with no separate fire/render step, which is essential behaviour an agent could not infer.

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

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

Front-loaded with purpose and the write-the-script rule, then organised into pricing, post-call, language and idempotency sections. Dense and heavily capitalised for a costly tool, which is defensible, but the wall-of-prose density and shouting reduce scannability slightly.

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 16-parameter, spend-incurring, open-world generator with no output schema, the description covers what is produced, how the result is retrieved (wait_for_generation then get_video), failure states, and refusal conditions. Nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real decision value by ranking the price levers (seconds_per_image 5 is ~40% cheaper than 3, 2 is ~50% dearer; gpt-image-2.5 is priciest, quote it; style_id forces the expensive model). Some of this restates the schema descriptions, so it is not pure addition, but the trade-off framing exceeds 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?

Opens with a specific verb and concrete output: a narrated script turned into AI-generated images with captions. Crucially it states the division of labour ('YOU WRITE THE SCRIPT, AND ONLY THE SCRIPT... never write the pictures'), which separates this from script-and-prompt siblings like generate_story_video. An agent can tell what it produces and what its own input responsibility is 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 about the pre-call workflow: show the script to the user as plain text, iterate for free, price with estimate_only, quote the scene count and price, ask for a go naming this purchase. It also routes to get_recipe for writing advice and list_image_story_styles for styles, and names the post-call path (wait_for_generation, then get_video).

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

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

Goes far beyond the annotations: it discloses the token cost model (per-second rate varying by resolution), that audio length is server-measured and rounded up, that unmeasurable audio is refused with nothing charged, that an external URL consumes a media-ingest slot, and that a reused idempotency key replays the first job. These details are consistent with `destructiveHint: true`, `openWorldHint: true`, and `idempotentHint: false` rather than contradicting them.

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

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

The core action is front-loaded and the labeled CAPS sections (WHEN, CONSENT, COST, WAIT, IDEMPOTENCY) make it navigable, but the description is very long and repeats schema content such as the resolution price ratio and the audio-account restriction. For a complex tool some length is warranted, but this is dense and over-emphasized rather than 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?

Covers everything an agent needs for a costly, consent-sensitive generation: cost and estimation flow, the required prior `generate_audio` step, consent policy, card/waiting protocol, idempotency hazards, and what is returned. There is no output schema, but the description states the immediate return (job id) and the final result's length.

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

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

With 100% schema coverage, the baseline is 3, but the description adds meaning not in the schema: the absence of any length argument, the server-side measurement and rounding of audio length, the media-ingest cost of an external URL, and the consent constraint on `character_image`. Much of the rest (resolution cost, audio account restriction) duplicates the schema descriptions, keeping it below 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: takes a picture plus an audio file and generates a lip-synced video of that person. It distinguishes the tool from siblings by specifying exactly which inputs it consumes (a `generate_audio` result) and what it returns (a job id and a video exactly as long as the audio). An agent can tell this apart from generate_video or motion_control without opening schemas.

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

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

Explicitly names when to use it (talking avatar, presenter, voiceover on a face) and when not to (never a real person without permission, never a public figure or celebrity). It also routes the agent to alternatives: make audio with `generate_audio` first, use `wait_for_generation` rather than polling, and do not call `show_generation` because the card is already open.

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

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

Annotations only mark it write/destructive/non-idempotent; the description adds the genuinely behavioral facts an agent could not infer: the call returns immediately and parks, it charges the frames stage now and refuses an account that cannot afford the whole episode, a generating portrait yields 409, writing_failed is terminal and unchained, and a reused idempotency_key replays the first job regardless of settings. It also spells out the after-states (starting, generating_frames, frames_review) and both card and no-card paths. No conflict with the annotations: destructiveHint aligns with the token spend, and idempotentHint=false aligns with the replay warning.

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 sentence one, but the body is roughly 450 words of ALL-CAPS labels, parentheticals and cross-references that are hard to scan. Some material restates global server rules (the SPENDING RULES and IDEMPOTENCY reminders are explicitly flagged as already being in this server's instructions), which dilutes the tool-specific content.

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

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

For a multi-stage, token-spending, card-mediated tool with 10 parameters and no output schema, almost every operational question is answered: cost quoting and tilde rules, sizing guidance, image-model offer, idempotency, failure and recovery paths, and what happens on both the card and terminal-response variants.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `scenes` is refused so the idea must be plain prose, `duration_seconds` is a length in seconds drawn from the model's published durations and never a scene count, a non-default `start_frame_model` requires a fresh estimate_only, and `cast_member_ids` is required vs forbidden depending on cast mode. These are cross-parameter constraints beyond the per-field schema text.

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

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

States a specific verb and resource plus exact scope: 'Starts an AI Video Story EPISODE (stage 1 of 3)' that writes the episode, draws the opening picture of every scene, and parks for review. The 'stage 1 of 3' framing plus 'before any video generates' cleanly separates it from fire_story_video and render_story_video 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?

The WHEN block names concrete preconditions (series picked and FULL entry fetched via list_series with series_id and video_model, idea settled, cast drafted and portraits bought for a cast.required series, user go-ahead) and points to the get_recipe story-episode flow. It also names the explicit alternatives: regenerate_story_frame when every frame failed, and 'do not offer delete_video', with the reason.

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: async/non-blocking behavior, consent rules for real people, the seedance refusal warning, the card already being opened, the no-polling rule, 1-3 (up to ~6) minute timing, token spend, and idempotency-key replay semantics. The only gap is that the annotations declare destructiveHint=true while the description never frames the operation as destructive — it says 'spends tokens' but not that a job cannot be undone or that credits are consumed even on refusal. Not a contradiction, but an underused opportunity.

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?

Labeled sections (WHEN, CONSENT, CARD, WAIT, TIMING, COST, IDEMPOTENCY) make it scannable and the non-blocking contract is front-loaded in sentence one. It is dense and pushes the practical limit of length, but nearly every clause encodes a distinct failure mode an agent would otherwise hit.

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 16-parameter generative tool with no output schema, the description covers the return value (job id), the card side effect, the required follow-up call, waiting/timing expectations, and the pricing flow. An agent has everything needed to invoke it and handle the result without guessing.

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

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

Schema coverage is 88%, so the schema already carries most parameter meaning and baseline would be 3. The description still adds real workflow semantics on top: price with `estimate_only: true` in the same message, never reuse an `idempotency_key`, and the scenes/images mutual-exclusion consequences. `end_image` and `keyframes` remain 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?

Opens with a specific verb+resource and an explicit async contract: 'Starts an AI video on the signed-in account, opens the aicut card and returns the job id at once; it does NOT wait.' That distinguishes it immediately from `wait_for_generation`, `show_generation`, and `generate_story_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?

Gives an explicit WHEN trigger, a prerequisite ('Call `list_models` first this session'), a recipe pointer, and named alternatives/handoffs (`show_generation`, `wait_for_generation`, `generate_story_video` for cast members). Exclusions are stated, not inferred.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial behavioral context: the four-value status lifecycle, expected latency, the non-obvious rule that an un-describable video reports `failed` rather than empty `succeeded`, and the absence of background timers. This is exactly the kind of operational detail annotations cannot express.

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

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

Front-loaded with the core behavior and the WHEN/TIMING labels make it scannable. Minor overlap between 'poll every 5-10 seconds' and 'wait `poll_after_seconds` rather than picking your own interval' creates a brief tension the reader must resolve, and the untrusted-text block, while valuable, runs long.

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

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

No output schema exists, so the description must carry the return contract — and it does: `status` values, `analysis.text`, `error.message`, and `poll_after_seconds`. It also warns that the result is untrusted third-party text and must not be rendered as HTML/Markdown, which is essential safety context for a tool that returns free-form model output.

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

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

There is a single parameter with 100% schema description coverage ('The analysis id returned by `analyze_video`'), so the schema already does the work. The description adds only the signed-in-account scoping, nothing about id format or origin beyond what the schema states. 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: returns the current state of one video analysis on the signed-in account, plus its result once finished. An agent can immediately distinguish it from `analyze_video` (which starts one) and `list_analyses` (which enumerates many).

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 WHEN block names the trigger explicitly (after `analyze_video`) and the exit condition (`status` is `succeeded` or `failed`), and instructs polling every 5-10 seconds until then. It also names the alternative interval source — `poll_after_seconds` — and tells the agent to prefer it over its own cadence.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds behavior the annotations cannot: it is a non-blocking snapshot, polling is wrong, and the status lifecycle is enumerated (queued/processing/succeeded/failed with url vs error.message). It even specifies the intended reporting behavior for the result.

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 definition, then WHEN, then OUTPUT — a clean triage order with almost no waste. The all-caps labels (SINGLE, IMMEDIATE, WHEN, OUTPUT) are slightly stylized, but each sentence carries distinct information.

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

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

For a single-param read with no output schema, the description covers the gaps that matter: that it does not block, the full status enumeration with what url and error.message mean, and how the result should be surfaced to the user. Nothing an agent needs in order to call and interpret it 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?

There is only one parameter, and the schema already documents it fully (the job id returned by generate_audio) at 100% coverage, so the description correctly need not repeat it. It adds no format, source, or lookup guidance beyond the schema, which is the baseline-3 case.

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: reading ONE audio job's current state, plus the key property that it waits for nothing. It also explicitly distinguishes itself from wait_for_generation, generate_audio, and show_generation, so an agent can pick it without opening siblings' schemas.

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

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

Gives an explicit WHEN scope (one job's raw fields now: cost, refund, failure reason), names the three alternatives and the conditions that select them, and adds a hard exclusion: 'Do not poll it.' Nothing about routing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely non-obvious behavior: top_up_url is returned only under specific conditions and is the ONLY link to give for adding tokens. It slightly under-delivers on what happens when the account is unauthenticated or the call errors, but the top_up_url rule is exactly the high-value context an agent would otherwise get wrong.

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

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

Front-loaded with the verb and return values, then a WHEN block, then the critical top_up_url caveat, then the pricing pointer. Every sentence adds decision-relevant information; nothing repeats structured fields.

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

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

With no parameters, no output schema, and a simple read operation, the description does the work the missing output schema would otherwise do by naming the returned fields (balance, plan tier, top_up_url). It covers triggers, return shape, and the one risky downstream action an agent might take.

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. The description correctly spends no words on inputs and instead redirects to parameterized siblings (estimate_only: true for pricing), which is the right allocation of attention.

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 ('Returns the signed-in aicut account's token balance and plan tier') and enumerates both return values. An agent can immediately distinguish it from adjacent tools like list_models or get_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?

Gives explicit WHEN triggers: before the first priced ask of a session, when the user asks what they have left, or after a generation fails for lack of tokens. It also routes to alternatives for pricing ('list_models, or estimate_only: true for audio'), covering both when-to-use and where-else-to-go.

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, yet the description adds genuinely new behavior: the call never blocks, polling is prohibited, and the `status` state machine is spelled out including the terminal `failed` case where `error.message` carries the reason. It even prescribes how to present the result rather than dumping JSON.

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 identity, then WHEN, then anti-patterns, then output handling. Every sentence carries distinct information; no filler or restatement of the title.

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

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

With no output schema, the description still explains the returned status values, where the finished file lives (`url`), and where failure reasons appear (`error.message`). For a one-param read tool this is fully sufficient to call and interpret 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% and the single `id` param already documents its provenance ('The job id returned by `generate_image`'). The description adds no further syntax, format, or validation detail beyond what the structured schema supplies, 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 ('One image job's current state: a SINGLE, IMMEDIATE read that waits for nothing') and immediately contrasts with `wait_for_generation`, `generate_image`, and `show_generation`. An agent can pick this over any sibling 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 WHEN clause ('only for one job's raw fields now'), explicit negative guidance ('Do not poll it'), and named alternatives for both the waiting case and the display case. When-to-use and when-not-to-use are both covered.

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

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

With readOnlyHint already declared, the description still adds substantial non-annotation context: the full terminal/non-terminal status vocabulary, the semantic trap that `posted` only appears on platform confirmation, `unconfirmed` being terminal and potentially live under the user's name, and the timing/polling profile (TikTok sub-minute, YouTube/Instagram 1–5 min, poll every 10s, no background timers). The 403 `insufficient_scope` analysis — that a read takes the same permission as a publish, so a live post stays live but cannot be read back until reconnect — is behaviorally important and not derivable from 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 most important fact (what the platform reports) before the status dictionary, and statuses are laid out as a scannable enumeration. It is dense and long for a single-parameter read tool — the 403 passage and the reference to `prepare_post`'s REFUSALS could be trimmed — but nearly every sentence carries operational value.

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

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

There is no output schema, so the description must explain return values, and it does: it enumerates every status value, explains the auxiliary fields (`post_id`, `fail_reason`, `scheduled_at`, `schedule_custody`), and describes timing expectations and polling cadence. An agent has everything needed to call it correctly and to interpret and act on 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% and there is a single parameter, so the schema already documents `post_id` and its origin. The description confirms the identifier is the `post_id` returned by `prepare_post` but adds no format or validation detail beyond what the schema states. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description opens with a precise verb+resource+scope: it returns what the platform reports about a post, plus `post_id` when live and `fail_reason` when not. It is immediately distinguishable from the sibling `publish_post` (which creates the post) and `prepare_post` (which stages it). An agent knows exactly what this returns without opening the schema.

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

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

It states WHEN explicitly: 'after `publish_post`', and names `prepare_post` as the origin of the `post_id`. It also routes the agent through failure paths: on `unconfirmed` tell the user to check the account and do not republish (double-post risk), and on 403 `insufficient_scope` stop and instruct a reconnect. There is no explicit 'do not use this for X' exclusion, which keeps it just short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: the output is text, the tool is preparatory, and it does not itself authorize paid downstream calls.

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 return type and then enumerates the recipe values. The long enum list is dense but each entry earns its place by clarifying a valid option. The guidance sentences are compact and purposeful.

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

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

For a read-only guide tool with no output schema, the description says it returns text and when it should be read. It also explains the authorization boundary for paid calls. It does not describe the internal recipe format in detail, but sufficient context is provided 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 100% and the enum already lists valid recipe names. The description adds useful semantics by briefly explaining what each recipe represents, going beyond the schema's minimal 'Which recipe.' 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?

The description uses a specific verb and resource: it returns a step-by-step recipe as text. It enumerates every supported recipe type, making the tool's scope unambiguous and clearly separating it from the generation/action siblings such as generate_video or generate_image.

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 timing guidance: 'Read it before a flow's first call.' It also warns that the recipe is a guide, not user authorization, so paid calls still require their own price and ask. It does not name alternatives or exclusions, but the core when-to-use condition is explicit.

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

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

Beyond the readOnly/idempotent annotations, it discloses cost and side effects ('Free, instant, creates nothing'), the failure mode ('a video outside the published trend set answers 404'), a guaranteed null field ('`series.selected` is always null and `series.reason` says why'), and a prompt-injection warning about untrusted caption/hashtag/brief text. These are all facts an agent cannot get from the annotations or schema, and none of them contradict the readOnly/idempotent hints.

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

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

The critical constraint (new original video, not a copy; no series chosen here) is front-loaded and the WHEN/route ordering is logical. It is dense and heavily capitalized, with several ideas packed into one block, so it is slightly heavier than needed, but no sentence is filler.

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

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

There is no output schema, so the description carries the full burden of explaining return values, and it does: public row, niche with premise, brief, next_steps, and the always-null series fields. Combined with the 404 note and the injection guidance, an agent has everything it needs to call this 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% and the schema already documents `trend_id` as 'A trend video's `id` from a `list_trends` row. Not a url.' The description reinforces this with the 404 consequence and the contrast against `analyze_video`'s url parameter, adding a little error-handling meaning beyond the schema, but the core semantics are already structured.

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+constraint ('returns ONE trend video's public row, the NICHE it belongs to, a written `brief`... and `next_steps`') and explicitly enumerates the returned fields. It also carves out a clear boundary against siblings by stating what it does NOT do (choose a series) and naming `list_series` as the tool that does.

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 ('right after the user picks a video from `list_trends`, or hands you a trend id and asks how to make one like it') and an explicit alternative for a different input type ('`analyze_video` takes an arbitrary url'). It also lays out the downstream route (analyze_video → list_series → generate_story_video), so the agent knows where this tool sits in the workflow.

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

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

Annotations already cover read-only/idempotent safety, but the description adds substantial context they cannot carry: the call is non-blocking, the full status taxonomy and which states are terminal, that frames_review means waiting on the user, that writing_failed is uncharged and cast-preserving, and the refund semantics of a failed render. This is exactly the behavioral detail an agent needs to interpret results 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?

Front-loaded with the core constraint ('waits for nothing') and organized with WHEN / OUTPUT markers; every clause carries real meaning. It is dense and fairly long for a one-parameter read tool, but the length is driven by genuinely necessary state semantics rather than filler.

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

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

With no output schema, the description takes on the burden of explaining return-value semantics and does so: status values, error.message, story.stage transitions, story.render verdicts, and a closing instruction on how to present results. Nothing material is left unclear.

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 required parameter with 100% schema description coverage, and the schema already states which tools produce the id. The description adds no syntax or format detail about `id` itself, only about what the returned status fields mean, so the baseline of 3 applies.

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

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

States a specific verb and resource ('One video job's current state: a SINGLE, IMMEDIATE read') and explicitly separates itself from wait_for_generation (waiting) and show_generation (displaying). An agent can pick this tool over its many 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 when ('only for one job's raw fields now'), when-not ('Do not poll it', 'not how you wait'), and names both alternatives plus a concrete trigger scenario ('when the user says something failed'). The routing guidance is unambiguous and complete.

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 given annotations: discloses the cost model ("spends NO tokens; counts against the daily utility allowance") and a strong safety disclosure that the returned `prompt` is untrusted data, including the prompt-injection risk from words drawn in the image. No contradiction with `readOnlyHint: false` / `openWorldHint: true`.

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

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

Front-loads the return value and the follow-on action, then layers cost and safety notes. Dense with parentheses and semicolons, which slightly hurts scanability, but no sentence is filler.

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

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

For a single-parameter tool with no output schema, the description covers the return value (`prompt`), where the input can come from, the failure case, the cost, and the security handling of the output. Nothing material is left for the agent to infer.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic constraints the schema lacks: accepted URL sources are an image url, an `upload_media` url, or a generated image's url, and cross-account aicut images are rejected. The "unchanged" requirement in the schema is complemented, not repeated.

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

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

States a concrete verb+resource: returns a text `prompt` that would regenerate the given image, equating it to the web app's "copy prompt from image". It also names the downstream sibling (`generate_image`) so the agent can place it in a workflow rather than guessing.

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

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

Explicitly says what to do with the result ("pass it to `generate_image`") and gives an exclusion case (another account's aicut image is rejected). It stops short of contrasting with siblings like `get_analysis` or `describe_cast_member`, so the routing picture is clear but not exhaustive.

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 write/non-idempotent/open-world behavior, and the description adds real value beyond them: the result lands on the account, it consumes one daily media allowance slot, and the returned `url` is accepted by any video input. The only blemish is an internal inconsistency between '3-30 s' and 'up to 20 s' that muddies the length contract.

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

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

Two tight sentences, purpose front-loaded before the WHEN clause, no padding. The trailing duration clause is duplicated with conflicting numbers, which is wasted and confusing text rather than excess length.

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 trigger, the cost model, and the return value even without an output schema, which is enough to call it correctly. The contradictory duration limits (3-30 s vs up to 20 s) leave an agent unsure of the accepted source length.

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 at 100% schema coverage, the schema already defines the input fully. The description adds only the passing note that any video input accepts the resulting `url`, which is about output, not the parameter itself, so baseline 3 applies.

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

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

States a specific verb+resource+source: turns a TikTok link into a clip on the account. The TikTok-specific framing cleanly separates it from siblings like import_video and upload_media, and it says what comes back (`url`).

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 explicit 'WHEN: the user gives a TikTok link as a clip to use' gives a clear trigger condition. It stops short of naming import_video or upload_media as the alternative for non-TikTok sources, so the routing is clear but not fully closed.

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

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

The description adds substantial behavior beyond annotations: it states the operation is free for uploads, link ingestion costs one slot, the return value is an id for prepare_post, and idempotency_key replays the first job whatever the settings. It also warns never to reuse the key for a new generation. These are exactly the operational details an agent needs for a non-readonly, open-world import.

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: purpose first, then source modes, cost, permission constraint, and idempotency warning. Every sentence carries operational information, and the telegraphic style suits a tool definition without wasting space.

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

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

With no output schema, the description still explains the meaningful return value (id for prepare_post). It covers prerequisites, source handling, cost, permission constraints, and idempotency behavior, which is complete for this two-parameter import 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?

Even though schema coverage is 100%, the description adds real meaning to both parameters. For url, it explains the local-file workflow via confirm_upload versus a public https link, and for idempotency_key it explains replay behavior and the danger of reuse for a new generation.

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

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

The description states a specific verb and resource: it puts an externally made video onto the account as a finished video, with upload or https link as the source. It clearly distinguishes this from video generation by saying the video is NOT made on aicut, and it names the returned id for prepare_post. However, it does not explicitly differentiate itself from close siblings such as import_link or upload_media.

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 useful usage context: use it for videos not made on aicut, upload a local file and pass the confirm_upload url, or use an https link at the cost of one ingest slot. It also includes the important restriction to only import content the user may post. It stops short of explicitly saying when to use this instead of import_link or upload_media.

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

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

Goes well past the readOnly/idempotent annotations: discloses that entries include web-app analyses and transcripts (format "text" vs "markdown"), that the analysis body is omitted in favor of length/format, and that whole result is untrusted model-generated text that must never be followed as instructions or rendered as HTML/Markdown. That is exactly the safety and content-shape context an agent needs.

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

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

Front-loaded with purpose, then WHEN, then behavioral caveats in capitalized labels, which makes scanning easy. It is on the long side and the "do not report a result from this tool" point partially repeats the preceding sentence about omitted 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?

With no output schema, the description carries the return-shape burden and does so: per-entry `analysis.length` and `analysis.format`, pagination via `next_cursor`/`has_more`, and a pointer to get_analysis for the body. Nothing needed to call or interpret the result correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by tying `cursor` to the previous `next_cursor` and gating it on `has_more`, which the schema does not mention. It does not restate the `limit` range or default, but that omission is minor given the schema is fully described.

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

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

The first clause names the resource and its scope ("The account's video analyses"), plus ordering ("newest first") and pagination semantics. It is clearly distinguishable from analyze_video (which creates one) and get_analysis (which fetches the text).

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

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

An explicit WHEN block covers both triggers: the user asking what they have analysed, and a pre-check before starting a new analysis because a duplicate may already exist. It also names the follow-up tool (get_analysis with the id) for the actual content.

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/closed-world, so the bar is lower. The description adds genuine context the annotations cannot: result ordering, pagination contract (`cursor` = previous `next_cursor` while `has_more`), and the important provenance distinction that web-app audio is included while job-internal clips 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?

Front-loaded with the core statement, then pagination, then WHEN, then scope exclusion — a logical order with no filler. The final parenthetical is dense but carries real disambiguation value, so it earns its place despite slight length.

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

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

No output schema exists, and the description does not enumerate the fields of an audio record, which is the main remaining gap. However, for a simple two-parameter read-only list tool it covers invocation, paging, ordering, and content scope thoroughly enough to call it correctly.

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

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

Schema coverage is 100%, so 3 is the baseline. The description goes slightly beyond the schema by explaining the cursor/next_cursor/has_more relationship as a paging loop, which clarifies how the two parameters interact rather than restating them.

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 ('The account's audio generations, newest first') and adds ordering. Critically, it carves out scope against siblings: top-level account audio including web-app output, but excluding clips other products generate inside a job, which separates it from per-generation tools like get_audio or job-scoped audio.

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 WHEN clause gives concrete triggers ('user asks what they have made', 'you need a voice-over, track or sound effect from an earlier session') and the exclusion sentence defines when-not. It does not name sibling alternatives (e.g., get_audio for a single item, list_voices for voice inventory), so routing is strong but not fully explicit.

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

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

Beyond the read-only and idempotent annotations, it discloses that this creates nothing and spends nothing, describes the returned fields, explains paging through `cursor`/`has_more`, and maps each kind's ids and image URLs to downstream tools. It also surfaces the important behavioral risk that `world` does not identify the series and cannot answer 'same cast as last time' alone.

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

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

The description is front-loaded with the return shape and then moves into usage, warnings, id semantics, and paging. It is longer than a typical list-tool description and contains some repetition around `world` not identifying series, but most sentences carry useful cross-tool or cost-risk information.

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

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

There is no output schema, so the description carries the burden of describing return values, and it does so thoroughly: kinds, fields, ids, image URL behavior, and paging. Combined with the annotations covering safety, it gives an agent enough context to call and interpret the tool correctly.

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

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

The input schema already has 100% description coverage for both parameters, including the default for `limit` and the meaning of `cursor`. The description reinforces paging by saying to use `cursor` from the previous `next_cursor` while `has_more` is true, but it adds little parameter-level meaning beyond the schema.

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

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

The description states a specific verb and resource: it returns characters saved on the account, newest first, in two explicitly named kinds (`uploaded` and `cast_member`). It also describes the distinguishing fields and the difference between the two kinds, so an agent can tell what this tool returns versus other list tools.

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

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

It gives an explicit WHEN section: the user wants to reuse a character or see what the account has. It also names `generate_cast` as the alternative for drafting a fresh cast and explains why matching by `world` to a series is unreliable, including the cost consequence of a wrong pick.

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 carry the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lowered. The description adds genuine value with the pagination contract ('cursor = the previous next_cursor while has_more') and the note that web-app-created images are included, but it says nothing about ordering stability, freshness/eventual consistency, or result caps beyond the schema's limit.

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 compact fragments, front-loaded with scope and ordering before usage guidance — zero filler. The telegraphic style ('while has_more', 'To let them CHOOSE one') is efficient but slightly clipped, costing a bit of readability.

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

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

With no output schema, the description still surfaces the key response fields an agent must handle (`url`, `next_cursor`, `has_more`), which is exactly what's needed for a paginated list. The omission is the undocumented `status` filter, leaving one of three parameters unexplained end-to-end.

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

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

Schema coverage is 67% and both documented params restate what the schema already says; the description's cursor explanation is a near-duplicate of the schema text. The `status` filter has no description in either place beyond the single-value enum, and the description never mentions it. Baseline 3 fits for a schema that does most of the work with one unexplained param.

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 opener names the resource (the account's images), the scope (web app included), and the ordering (newest first), which is enough to distinguish it from get_image (single item) and show_images (interactive chooser). It never states the verb explicitly, but the 'newest first' + paging framing makes the list semantics unambiguous.

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

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

It gives an explicit WHEN clause ('the user asks what they made, or you need an earlier image's url') and names the alternative for a different intent ('To let them CHOOSE one: show_images'). An agent can route correctly without inspecting any schema.

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

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

The description goes far beyond simple annotations by detailing critical system behaviors: cost implications ('five times the cheapest look's per-image price'), required workflow change (re-quote with `estimate_only`), and strict output formatting (max 3, markdown images, never dump the list).

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 very long and dense. While it could benefit from structural formatting (like bullet points) to improve readability, every sentence in the text provides necessary, unique information that would be missing from structured fields alone.

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

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

Given the complexity—involving unique error codes (503), significant cost changes, and specific UI presentation requirements—the description is maximally complete. It leaves virtually no ambiguity for the AI agent.

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?

Since the input schema has zero parameters (0% coverage applies), the description cannot add semantic meaning beyond the baseline score. The comprehensive coverage means the description's ability to help with parameters is irrelevant here.

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

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

The description provides a highly specific definition, distinguishing 'styles' as 'named looks (a character, a rendering treatment, an art direction)' for image-story videos. It is far more specific than a generic image generation tool.

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 explicit conditions for use: call it when the user asks what looks exist or wants a consistent stylised world. It also implicitly guides usage by contrasting the expensive styles with the 'ordinary photorealistic look' default.

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?

Even with read-only annotations already covering safety, the description adds substantial behavioral context: unfiltered results cost several thousand tokens, unknown tags produce a 400, cursor paging requires identical filters, and pricing shapes differ between video/image and audio models.

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

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

The description is long, but its length is justified by the catalog complexity and it is structured around WHEN, narrowing, tags, paging and pricing. Some emphasis-heavy wording is repetitive, but the key guidance is front-loaded and 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?

There is no output schema, so the description carries the burden of explaining return shapes and does so: tag vocabulary in responses, `ignored_query_terms`, `total_matching`, `has_more`, `next_cursor`, and the two pricing shapes. An agent has enough information to call and interpret the tool correctly.

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

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

Schema coverage is 100%, but the description still adds meaningful semantics beyond the schema: it explains the closed tag vocabulary, how `query` drops unmatched terms into `ignored_query_terms`, and when to use `limit` versus retrieving every match.

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 and resource: it returns AI video, image and audio models with their parameters, inputs and pricing. It clearly distinguishes this catalog tool from generation siblings (`generate_video`, `generate_image`, `generate_audio`) and from `list_voices`.

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 WHEN guidance: call before the first generation of a session, narrowed and never as the whole catalog. It names alternatives and edge cases, including that voice ids come from `list_voices` and that model ids and supported combinations cannot be guessed.

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

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

Annotations already declare this is a safe read-only, idempotent, closed-world operation. The description adds valuable behavioral context beyond annotations: the two response modes, the prerequisite relationship to `generate_from_niche`, and the caveat that `price.tokens` reflects default settings only. It does not cover permissions or rate limits, but those are less relevant for this read-only listing tool.

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

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

The description is dense but front-loaded around the two `slug` modes, and most sentences carry actionable guidance. It is slightly telegraphic in places, but there is little wasted text for a tool with an important downstream workflow dependency.

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 one optional parameter, no output schema, and read-only annotations, the description is complete enough to call correctly. It explains both return modes, the fields available in each, the shortlist behavior, the price caveat, and the `generate_from_niche` follow-up.

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

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

Schema coverage is 100%, and the schema already explains omitting `slug` for cards versus supplying one for a full niche. The description adds meaningful semantics: the slug mode is required before `generate_from_niche` and returns `inputs`, `settings`, and `revision`, which helps the agent understand why and when to pass it.

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

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

The description states a specific resource and verb: listing aicut trend-template niches, with the distinct one-shot video format scope. It also distinguishes these from AI Video Story series via `list_series`, so an agent can separate it from siblings before inspecting schemas.

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

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

It explicitly covers both usage modes: without `slug` for cards and with `slug` for a full single niche. It also gives workflow guidance, including that the slug mode is required before `generate_from_niche`, and says to shortlist 3-5 fits rather than dump the list.

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

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

Annotations already cover read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful context that access is free and that a returned `id` can be used as a `reshot_video` `template`, but it does not describe return format or pagination.

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

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

It is short, but the structure is weak: "Free" is front-loaded and "who is where, when" is cryptic rather than informative. It is concise without being especially clear.

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

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

For a zero-parameter read-only listing tool, the description gives the cost and an important `id` linkage to `reshot_video`. However, with no output schema, it still does not clearly explain what a Reshot template is or what the listing returns.

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

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

The tool has zero input parameters, so there are no parameter semantics to document beyond the baseline. The description's mention of an output `id` is helpful but not part of input parameter documentation.

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 title identifies listing Reshot templates, but the description never clearly states that verb/resource relationship. "Reshot gallery clips: who is where, when" is opaque and does not distinguish this tool from siblings such as reshot_video or list_videos.

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

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

The only usage-like information is "Free." There is no guidance on when to use this list versus reshot_video or other listing tools, and no prerequisites or exclusions are stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine operational context beyond that — two-call shape, null-not-zero semantics, quoting rules, response-size warning for `video_model`, and presentation prohibitions (never paste `preview_url`, never dump the catalogue) — which is meaningful but pitched at the calling agent's output discipline rather than the tool's own behavior.

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

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

It is front-loaded with identity and the browse rule, and the two-mode structure is legible. But it is very long and heavily shouted in caps, with some restatement (the no-dump/no-paste instructions recur) that crowds out faster scanning.

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

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

With no output schema, the description carries the return shape and does so thoroughly: it enumerates the compact-catalog fields, the full-entry pricing blocks, the estimation flags and their interaction, and the null-handling path. An agent has everything needed to call 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% and both parameters already document their shape and default-vs-omit behavior. The description reinforces the selection rule (use `defaults.video_model` unless the user named a model) and states the refusal case, but does not add much that the schema text lacks.

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 ("Lists aicut's AI Video Story series (niches)") and defines what a series is, then explicitly separates the browsing job (`browse_series`) from this data-read job. An agent can place it among the ~60 siblings 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 when/when-not: call `browse_series` FIRST when the user is choosing by eye, this tool is the data read behind that choice and the fallback with no cards. It also prescribes call discipline ("TWO CALLS", never once per series) and the lookup-vs-list decision driven by `series_id`.

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 readOnly/idempotent annotations by disclosing empty-state semantics ("An empty `ideas` list means the series ships none"), the 404 case, and hard presentation constraints (offer at most 3, one line each, end with 'or tell me yours', never paste full text). Some phrasing such as "Free, instant, creates nothing" restates what the annotations already declare, which keeps it from a 5.

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

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

Purpose is front-loaded, but the body is a dense run-on mixing usage rules, output formatting, downstream constraints, and empty-state handling, with heavy all-caps emphasis. Most clauses earn their place, yet the `idea` paragraph belongs to a different tool and dilutes this one.

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

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

With no output schema, the description still covers return semantics (a list of preset cards, brevity of items, empty-list meaning) plus the 404 error. What it lacks is any indication of item structure beyond "one line each," but that is a minor gap for such a narrow read.

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

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

Schema coverage is 100% and there is only one parameter, so the schema already carries the load; the description only adds the 404-means-unknown-id behavior. It also discusses an `idea` value that is not a parameter of this tool, which could momentarily confuse an agent mapping arguments.

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 with scope precision: "Returns ONE series' CURATED preset ideas (the authored cards the webapp shows on its idea step)." It also explicitly distinguishes itself from the sibling path an agent would otherwise take, naming generate_story_video and the default invent-your-own behavior.

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 when-not ("THIS IS NOT THE DEFAULT WAY TO GET AN IDEA: invent three of your own") and a narrow when ("call this only when the user asks what the SERIES itself suggests"), including a sample user utterance. It also lists the follow-up behavior after the call, so the agent knows the whole workflow, not just the trigger.

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?

Although annotations already declare this tool as read-only, non-destructive, and idempotent, the description adds substantial behavioral context. It explains `schedule_custody`, what an empty result means, that connecting requires a browser sign-in the API cannot perform, and how to interpret a subsequent 403 from `prepare_post` as missing `social:publish` permission rather than a bad account 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 definition is dense but front-loaded: it first states what is returned, then WHEN to use it, then explains the key return fields, edge cases, and permission caveats. Every sentence contributes operational guidance, including the empty-list and 403 scenarios.

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

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

There is no output schema, so the description carries the return-value burden and does so adequately by naming `id`, `connect_url`, `platform`, and `schedule_custody` and explaining their significance. It also covers the main failure modes an agent would encounter around connecting and publishing permissions.

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 are zero input parameters, so the baseline is 4. The description does not need to explain parameter syntax, and it uses the space instead to describe returned fields and operational meaning.

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

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

The description states a specific verb and resource: it returns connected social accounts for publishing, including the id `prepare_post` needs and a `connect_url`. It clearly distinguishes this read-only discovery tool from the related posting tools `prepare_post` and `publish_post`.

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 WHEN guidance: before any posting attempt and whenever the user asks where they can post. It also covers the empty-list case, instructs the agent to stop and share `connect_url` rather than retry, and explains the permission distinction versus `prepare_post`/`publish_post`.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real value beyond them: 'Free, instant, creates nothing,' the default that silently hides non-dialogue videos, and a security note that caption/hashtags/brief are untrusted DATA never to be rendered or followed. That is rich behavioral context an agent needs.

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 scope, then structured WHEN/PRESENTING/security blocks where each section earns its place. It is dense and long, with mild overlap between the description and the dialogue schema description, preventing a 5.

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

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

There is no output schema, but the description enumerates each row field (id, url, caption, hashtags, counts, outlier_ratio, published_at, cluster_id, is_new_channel_breakout), plus when to use, how to present, and the untrusted-field warning. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning: it clarifies the dialogue default hides rows and how to override it, and explains row fields like outlier_ratio and is_new_channel_breakout that matter for interpretation. This goes beyond the schema's own wording.

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

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

States a specific verb and resource (lists AI short-form videos tracked as trends) and disambiguates from siblings by defining it as aicut's own vetted /trends feed with real TikTok rows. An agent can distinguish it from list_videos or list_niches 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 WHEN block: what is trending/working now, what to make, or wants to recreate something that works. Also routes to get_recreate_brief for the chosen row and gives presentation guidance, leaving little to inference.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior. The description adds useful context beyond that: ordering is last used first, returned fields are url/kind/size, sources include app and MCP, and the call is free.

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 and mostly waste-free, with purpose, return fields, cost, and routing conditions packed into short phrases. The shorthand is efficient, though some phrasing such as 'the user answered after upload_media_widget' is terse enough to risk ambiguity.

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 with rich annotations, the description covers purpose, ordering, return fields, and cost. It still leaves gaps around parameter semantics, pagination/limit behavior, and when to choose list_uploads versus show_uploads.

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

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

Schema coverage is only 50%, and the description does not explain the kind filter or limit parameter. Its mention of link is routing advice toward import_link rather than a definition of the kind parameter's semantics.

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

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

The description clearly states that this lists recent uploads from app and MCP, ordered by last used, and returns url, kind, and size. It distinguishes itself from import_link for link uploads but does not clearly differentiate from the sibling show_uploads.

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 condition: after upload_media_widget or when the user means an earlier upload. It also routes link/TikTok-post cases to import_link, though it does not mention when to prefer show_uploads or other list tools.

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

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

Annotations already declare this a read-only, idempotent, non-destructive call, so the description is free to spend its words on non-obvious behavior — pagination contract (`cursor` = previous `next_cursor` while `has_more`), library scope beyond what the API can create, and the trap that `frames_review` reports `status: "processing"` while actually waiting on the user. That status-vocabulary warning is behavior an agent cannot get from annotations or schema.

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

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

Front-loaded with the list semantics and pagination, then WHEN, then the story-episode guidance — a sensible priority order. The `story_stage` enumeration is long and slightly overlaps the schema's `kind` description, but each stage gloss carries real disambiguation value for an agent deciding whether to wait or render.

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

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

With no output schema, the description compensates by describing row fields (`kind`, `story_stage`, `status`, `next_cursor`) and their meaning. For a three-optional-parameter list tool with full annotation coverage, an agent has everything needed to page correctly and route the result to the story 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?

Schema coverage is 100%, so the baseline is 3, and the description earns an increment by explaining why `kind` matters (story tools need the episode id) and how to read `story_stage` on returned rows, plus the fallback when `story_stage` is omitted. It adds little on `limit`, but the enum's downstream consequence is well covered.

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

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

The opening clause gives a specific resource and ordering ('The account's videos, newest first') and immediately bounds scope ('the whole library, including videos made in the web app and with products this API cannot create'). It is clearly distinguishable from get_video (single item), list_uploads (raw uploads) and the story generation tools.

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

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

An explicit WHEN clause names both triggering situations (user asks what they made; need a video from an earlier session), and it names the routing rule to siblings: 'THIS IS HOW YOU FIND A STORY EPISODE, and every story tool needs its id', with get_video indicated for the underlying job. When-to-use, why-to-use and alternatives are all present.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantive behavior beyond that: paging contracts (`total_matching`, `has_more`, `next_cursor`, same-filter continuation), the consequence of inventing an ID ("fails AFTER the job exists and is charged"), and the reseller limitation on `generate_audio`. That is meaningful disclosure the annotations cannot carry.

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

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

Front-loads the core claim and the ID-provenance warning well, and the per-entry field breakdown earns its space since there is no output schema. However it duplicates schema-documented facts (limit default 20/max 100, same-filter cursor rule) and leans on dense all-caps emphasis that makes the 300+ word block harder to parse than necessary.

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

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

With no output schema, the description fully covers the return shape (`id`, `provider`, `name`, `description`, `category`, `labels`, `preview_url`, `usable_for`, plus the `providers` envelope with null-count semantics). It also covers paging edges and filter interactions — nothing an agent needs to invoke and interpret it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: that only `audio` narrows ElevenLabs "and barely," why `limit: 100` is advised there, and that filters must match across cursor pages. It reinforces rather than replaces the schema, which is exactly the right division of labor.

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

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

Opens with a specific verb+resource+scope ("The WHOLE voice catalogue ... across ElevenLabs ... and OpenAI") and explicitly disambiguates from the sibling `list_models` ("`list_models` publishes none"). An agent knows exactly what this returns and what it does not.

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

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

Names the consuming tools and their parameter paths (`generate_audio`'s `voice`, `voice_left`/`voice_right`, `image_story`'s `voice`), states when to narrow with `usable_for`, and warns against the wrong alternative (`list_models`). It even prescribes a workflow (propose 2-3 voices with links, let the user pick before paid calls) with an explicit exclusion for multi-voice comparisons.

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

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

The description goes well beyond the annotation hints (destructive=true, openWorld=true): it explains the token-cost model (clip length × per-second rate), that the server measures the clip length, that unmeasurable clips are refused uncharged, the 3–30s (10s for portraits) bounds, the consent restriction on real people and celebrities, and the idempotency-key replay semantics. This is exactly the kind of pricing, refusal, and failure behavior the annotations cannot convey.

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

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

The description is front-loaded with purpose, then WHEN, CONSENT, CARD, WAIT, COST, and IDEMPOTENCY, so it reads as labelled sections rather than prose. It is long and mixes workflow protocol (card and wait narration rules) into a tool description, but nearly every clause carries operational information an agent needs.

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

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

There is no output schema, yet the description states the return ('the new job's id immediately'), gives the follow-up protocol, and says what to do when no card is present ('give the user the `url`'). Together with the consent, cost, and refusal rules, an agent can call the tool and handle the result without opening anything else.

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 earns one point above that by clarifying each input: there is no length argument (the server measures it), an external url consumes a media-ingest slot and must be quoted and created from the same url, and the 10-second cap for a still portrait is tied to `character_orientation`. It adds real meaning on top of the enum and property descriptions.

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

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

The first sentence names a specific verb and resource: it generates a video of a character from a picture performing a reference clip's motion. It also sharply separates the inputs ('the clip supplies the MOVEMENT only; the character comes entirely from the picture'), which distinguishes it from siblings like generate_video or edit_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?

An explicit WHEN block gives the trigger ('the user wants their character to dance, copy a move or perform a clip's motion'), and the text also states when NOT to call siblings ('do not call `show_generation`', 'no `get_*` polling') and routes to `wait_for_generation` and `estimate_only: true` instead. The consent and length-precondition rules add further constraints on when to call it.

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 far beyond the annotations (which only say non-read-only, non-destructive, non-idempotent): discloses the 30-minute expiry and why, the per-platform `account_limits` behavior (TikTok queries the platform vs YouTube/Instagram returning `aicut_api_limits`), and the actionable 403 `insufficient_scope` and 409 `episode_not_rendered` refusals with remediation. This is the kind of behavioral context annotations cannot carry.

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

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

Front-loads the most important fact (nothing is published) and the routing rule before the detail, and nearly every sentence carries decision-relevant information. It is still a dense single-paragraph wall with capitalized emphasis throughout, and a few lines duplicate the schema, so it is efficient 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?

For a 15-parameter, multi-platform staging tool with no output schema, the description covers every decision point an agent needs: prerequisites, render gating, platform-specific fields, scheduling semantics, and actionable error handling. Nothing essential to calling it correctly is missing.

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

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

Schema coverage is 100% and the schema is already detailed, but the description adds real semantics beyond it: fields are per-platform and a foreign platform's field is refused, the caption is sent exactly as given (never trimmed), and `schedule_at` only stages while `publish_post` commits. Some overlap exists (the disclosure-defaults guidance largely restates the schema), which keeps it from a 5.

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

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

States a specific verb (stages/prepares) and resource (a post of a finished video to a connected social account), and immediately distinguishes itself from the sibling that actually publishes (`publish_post`). The "NOTHING IS PUBLISHED BY THIS CALL" line removes any ambiguity about what the tool does versus its downstream sibling.

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

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

Explicit WHEN clause names the prerequisite tools (`list_social_accounts`, `list_videos`/`get_video` with `status: succeeded`) and the render prerequisite (`render_story_video` then wait for `story.stage: rendered`). It also names the alternative path — if the user is on a rendered card, call `review_post` instead and stop — which is exactly the sibling routing an agent needs.

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

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

Annotations only say destructive/not-idempotent/open-world; the description adds what is actually destroyed (post goes out under the user's name, cannot be removed from aicut), that the caption/visibility/disclosure are frozen, the exact per-platform call outcomes (`publishing`, `submitted`, `scheduled`, never `posted`), rolling per-account rate limits with counts, which refusals are free vs. slot-consuming, and that a 403 published nothing. This is far beyond the annotation payload and consistent with it.

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

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

Front-loaded with purpose and the irreversibility warning, and every block is labelled (WHEN, SCHEDULING, THE POSTING LIMITS) so it scans well. It runs long and repeats the 403 story twice (once in the scope paragraph, once in the closing sentence), which is more redundancy than the complexity strictly requires.

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

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

No output schema exists, and the description compensates by enumerating every status the call can return and what each means, plus the error codes and their remediation. Nothing an agent needs in order to call this correctly and report honestly is missing.

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

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

Schema coverage is already 100%, yet the description still adds meaning: `post_id` is the id from `prepare_post` or from the card confirmation message, and `schedule_at` should only be set when the user asked for a different time after confirming, with null meaning send now. It explains the intent behind the parameter, not just its type.

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 ("Sends a post staged by `prepare_post`, or schedules it") and immediately distinguishes itself from the two siblings that could be confused with it, `prepare_post` and `review_post`. An agent knows exactly which step in the publish pipeline this is.

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 section: after `prepare_post`, once the user has chosen and confirmed, with a precise definition of what counts as confirmation (named account/text/visibility/time, bare 'yes' only when immediately preceded, or a card message carrying the post id). It also names the required follow-up (`get_post_status`) and forbids workarounds on rate limits.

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

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

Goes well past the annotations: it discloses the return contract (`portrait_image_id` with `portrait_status: "generating"`), that the old portrait survives in the account's images, that each repeat is a fresh charge, that the price may differ from the draft's published rate, and the exact idempotency-key replay semantics. The token-spend and go/no-go rules add real behavioral context the `destructiveHint`/`idempotentHint` flags only gesture at.

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 in the first clause and the WHEN/ALTERNATIVES/CARD/AFTER/COST blocks are scannable. It is long for a four-parameter tool, and cost is stated three separate times while 'this server's instructions' is cited twice, which is some redundancy — but each block carries operational content rather than filler.

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