AlertForge

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

Adds substantial context beyond annotations: it is the server-side gate that blocks plan_overlay_pack, it fails on unrendered sheets, and it needs an authorized AlertForge account. The repeat-call behavior ('returns the same approval, does not re-approve or error') restates the idempotentHint already present, so that sentence adds little, but the gate and failure semantics are genuinely new.

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?

Every sentence carries actionable content, but it opens with the account/setup preamble before stating what the tool does, pushing the core purpose behind auth logistics. The setup URL is necessary yet consumes front-loaded 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?

For a one-parameter mutation gated on rendering and user consent, the description covers auth, precondition, failure mode, downstream effect on plan_overlay_pack, and idempotency. No output schema exists but the return is described as the same approval, which suffices.

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?

Single parameter with 100% schema coverage, so the baseline is 3. The description only implies provenance ('projectId returned by create_design_sheet'), which the schema already states, and adds no format or validation detail.

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 ('Records the user's approval of a rendered Style Sheet') and distinguishes itself from get_pack_status (rendering check) and plan_overlay_pack (consumer of the approval). An agent can place this tool in the workflow without opening any sibling schema.

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

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

Explicitly says to call it ONLY after the user has seen designPackage.imageUrl from get_pack_status and expressed approval, and tells the agent to poll get_pack_status until designPackage.status is "ready" first. Both the when and the not-yet cases are named with the responsible alternative tool.

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

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

Adds substantial context beyond the annotations: credit spend, subscription gating at execution rather than planning, per-alert partial failure semantics with the `error` field, and asynchronous return before rendering. The idempotency detail (same planId returns the same pack, no double charge) elaborates on idempotentHint rather than merely restating 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?

Dense but every sentence carries operational value — auth, billing, subscription, idempotency, partial failure, async. Slightly crowded, with billing and subscription split across separate sentences, but nothing 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?

Covers everything an agent needs for a mutating, paid, asynchronous tool: auth flow, cost, failure mode string, idempotent retry safety, per-entry error handling, and the required status-polling step. No output schema, but return-shape expectations are described.

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 planId parameter is fully documented in the schema. The description only reinforces that reusing the same planId is safe, which is an idempotency behavior rather than new parameter meaning, 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+resource: 'Consumes a plan from plan_alert_pack and creates its alert(s).' It names the upstream sibling that produces the input, so an agent can place it precisely in the plan→create→status workflow.

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 preconditions (approved AlertForge connection, OAuth sign-in, active subscription checked at this step) and explicit follow-up routing to get_alert_pack_status. It also tells the agent what to do if the call fails with 'subscription_required'.

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 idempotentHint=true, destructiveHint=false and openWorldHint=true, but the description goes further by explaining the concrete consequence: a repeat call with the same planId returns the same project rather than creating a second one or charging twice. It also discloses credit spend, the asynchronous return before rendering completes, and the approval gate that blocks plan_overlay_pack — none of which appear in the structured fields.

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

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

Dense but purposeful: one sentence per concern (prerequisite, action, idempotency, async follow-up, downstream gate). Slightly front-loaded on the OAuth setup rather than the core action, and the setup URL consumes space, but nothing is wasted padding.

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

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

Covers everything an agent needs to invoke correctly and continue the workflow: auth prerequisite, what is consumed and charged, idempotent retry semantics, the async boundary, and the exact next tool calls. No output schema exists, but the description names the key return field (designPackage.imageUrl) itself.

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 one fully documented parameter at 100% schema coverage, the schema carries the load. The description reinforces provenance ('a plan from plan_design_sheet') and the idempotency keyed on planId, but adds no format or validation detail beyond what the schema and annotations already state.

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 and resource ('Consumes a plan from plan_design_sheet, spending its quoted credits and creating the project'), which distinguishes it cleanly from sibling plan_design_sheet (planning) and approve_design_sheet (approval). An agent can identify the operation without opening the schema.

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

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

Gives explicit preconditions (approved AlertForge account connection, OAuth sign-in), the required upstream source (a plan from plan_design_sheet), and the exact downstream sequence: call get_pack_status to advance rendering, show designPackage.imageUrl, then call approve_design_sheet. It also warns that plan_overlay_pack will refuse until approval is recorded, which is genuine when-to-use routing.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and openWorldHint=true, but the description adds substantial context beyond them: it spends quoted credits, attaches scenes to an existing project, is safe to retry with the same planId without double-charging, and returns before rendering completes. This is exactly the behavioral context an agent needs for a mutation tool.

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

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

The description is dense but every sentence earns its place: prerequisite, core action, idempotency guarantee, and async follow-up. It is logically ordered from setup through execution to next steps.

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 asynchronous mutation tool with no output schema, the description covers authentication prerequisites, credit consumption, project attachment semantics, idempotency, and the required follow-up call. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents planId. The description still adds meaning beyond the schema by explaining that planId represents a consumable plan whose quoted credits are spent, and that reusing the same planId is idempotent. It stops short of format details, which the schema covers.

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 consumes a plan and attaches scenes to an existing overlay project. It explicitly distinguishes itself from create_design_sheet (which creates the project) and plan_overlay_pack (which produces the plan), so an agent can tell exactly what this tool does versus its 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 prerequisites (approved AlertForge account), the required prior step (plan_overlay_pack), and the required follow-up (call get_pack_status afterward). It also states what the tool never does — create a new project — which prevents misuse.

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

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

Beyond the annotations, it discloses that credits are spent, only the character slot is patched, the previous approval is cleared, retries are safe with the same planId, and approval must wait for the user. This adds real operational context on top of destructiveHint, idempotentHint, and openWorldHint.

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

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

The description is dense and mostly front-loaded, though it opens with setup/auth instructions before the core action. Every sentence carries useful information, with no filler.

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

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

For a destructive, credit-spending mutation with no output schema, the description covers auth, cost, idempotency, approval clearing, downstream polling, and the user-approval gate. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, and the schema already explains that planId comes from plan_style_sheet_character_edit. The description only reinforces reuse of the same planId for retries, so it adds little beyond the structured field.

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 queues the character-region change produced by plan_style_sheet_character_edit and patches only the character slot into the current Style Sheet. It is clearly distinguishable from the planning sibling and from approve_design_sheet.

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 makes the workflow explicit: obtain the plan first, retry only with the same planId, then poll get_style_sheet_character_edit_status, show the revised image, and call approve_design_sheet only after explicit user approval. Prerequisites (approved AlertForge connection, OAuth sign-in) are stated up front.

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

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

Beyond the annotations, the description discloses credit consumption, authorization requirements, entitlement-dependent downloading, idempotent behavior for repeated planId calls, immediate return semantics, and variable render timing. This is substantial behavioral context for an open-world, non-read-only 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 front-loaded with the authorization requirement, then credits, plan consumption, entitlement caveat, idempotency, and async status guidance. Every sentence contributes operational information without repetition.

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 one required parameter, no output schema, and annotations that establish the safety profile, the description covers the remaining essentials: auth, billing, idempotency, async behavior, status-checking, and download entitlement caveats.

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 planId definition already says it comes from plan_transparent_video. The description adds useful semantics by explaining that the planId is consumed and that repeated calls with the same planId are idempotent.

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 consumes a plan from plan_transparent_video and starts a transparent-video render. It clearly distinguishes this create/start operation from the planning sibling plan_transparent_video and the status-checking sibling get_render_status.

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 prerequisites: an approved AlertForge connection and OAuth-style authorization. It also explains when creation is allowed versus downloading, states that credits are spent, and directs the agent to get_render_status after the immediate return.

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 (openWorld, non-idempotent, not read-only), while the description supplies the valuable details: an upload to R2 and a time-limited signed download URL, plus the ZIP's contents. Auth and setup requirements are disclosed with a link. Cost/credit or failure behavior is not mentioned, keeping it below 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?

Auth requirement is front-loaded, then artifact behavior, then the disambiguation against the full themed artifact. The editorUrl mention is a little verbose but earns its place as a redirect instruction.

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 convey the return value, and it does (signed download URL, ZIP contents). Auth, setup link, and artifact-scope caveat round it out; only workflow timing and cost expectations are left implicit.

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

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

Schema coverage is 100% for the single projectId parameter and the schema already ties it to create_overlay_pack. The description adds no syntax or format detail beyond what the schema provides, 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 ("Bundles the pack's finished scenes into a flat ZIP") and explicitly names the artifact it is not (the full themed folder-tree from the web editor). An agent can distinguish it from sibling status/creation tools without opening the schema.

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

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

Gives a clear precondition (approved AlertForge account, OAuth flow) and an explicit exclusion pointing the user to the web editor's "Download pack" button for the richer artifact. It stops short of saying when in the workflow to call it (e.g., after get_pack_status reports completion), so it's 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?

Goes well beyond the annotations: it discloses that credits are spent (with where to find the price), that the operation is asynchronous and provider timing varies, and that the immediate return is only a renderId requiring polling. It also spells out the auth/setup requirement and supplies a setup URL, none of which the annotations 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?

Dense and largely waste-free, but the ordering buries the payload: the first two sentences are auth and billing logistics, and the actual purpose arrives third. Front-loading what the tool creates before the sign-in and credit boilerplate would help an agent triage faster.

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

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

With no output schema, the description carries the full burden of the return contract and does so precisely: an immediate renderId, asynchronous completion, the exact status tool to poll, the terminal status value, and the field name (`path`) to reuse downstream as characterImageUrl. Nothing needed 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?

There is a single parameter and schema description coverage is 100% — the schema already states 'a description of the character to generate, up to 600 characters.' The description's 'from a text description' adds nothing the schema lacks; no guidance on prompt phrasing or what makes a good prompt is offered. Baseline 3 is correct for a fully documented single parameter.

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

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

States a specific verb and resource — 'Generates a brand-new standalone character portrait from a text description via AI' — and preempts the most likely confusion with the video-generating siblings by adding 'this is a still image, not a video.' The word 'standalone' also distinguishes the output from sheet/pack-derived characters.

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 preconditions (approved AlertForge account connection, OAuth approval), a cost note pointing at list_alert_types' characterGenerateCredits, and the exact downstream sequence: poll get_alert_character_status until 'completed', then feed `path` into plan_alert_pack. What it never does is exclude the nearest sibling, create_style_sheet_character_edit, leaving the agent to infer which character-creation entry point applies when a style sheet already exists.

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 substantial context beyond them: it is free to call, safe to poll repeatedly, and reserved credits are automatically refunded on failure. It also discloses the auth prerequisite and references a setup URL, which are not captured in 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?

Dense but mostly justified — auth, setup link, cost, polling loop, and terminal states are all actionable. Minor deduction because the auth prerequisite and URL are front-loaded ahead of the core purpose, slightly delaying the one-line 'what it does' for a reader skimming.

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 tells the agent what to expect back ('completed' with a usable path/url, or 'failed'), how to interpret failure (credits refunded), and how often to re-poll. Nothing needed to invoke and terminate polling 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 single renderId parameter is already documented in the schema as coming from generate_alert_character. The description adds the polling cadence but nothing new about the parameter itself, 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 ("Read-only poll for a character generation") and names the originating tool generate_alert_character, which cleanly separates it from the many other status siblings (get_render_status, get_pack_status, get_style_sheet_character_edit_status). An agent can identify the tool without opening the schema.

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

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

Gives explicit operational guidance: call every few seconds, stop at 'completed' or 'failed', and pair with generate_alert_character. It also states the prerequisite (approved AlertForge account connection) and the OAuth path, so the agent knows both when to use it and what must happen first.

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 readOnlyHint/idempotent annotations: it discloses the auth requirement and setup link, that calls are free, that the render worker progresses alerts asynchronously outside this call, and that terminal states must be polled for. These are exactly the non-obvious operational traits an agent needs and that 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?

Dense but every sentence carries information — auth, cost, non-advancing semantics, return shape, polling. Minor deduction because it opens with the auth prerequisite rather than the core purpose, so the primary action is not fully front-loaded.

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 fully compensates by enumerating the status values and the returned fields (WebM result URL, OBS overlay URL, credit cost). Combined with the async/polling model, an agent has everything needed 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 packId is already documented in the schema as 'returned by create_alert_pack'. The description adds no further semantics about the parameter (no format, no validation, no behavior on invalid ids), so this is the baseline 3 where the schema does the work.

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

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

States a specific verb and resource — reports each alert's status in a pack, with the exact enumerated states (queued/running/succeeded/failed) and returned artifacts (WebM URL, OBS overlay URL, credit cost). It also explicitly distinguishes itself from the similarly named sibling get_pack_status, so an agent can disambiguate 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 an explicit prerequisite (approved AlertForge account connection), the OAuth flow instruction, and the exclusion: unlike get_pack_status, this call does not advance anything. It also prescribes a polling strategy ('poll at a reasonable interval until every alert reaches a terminal state') and warns that provider timing varies.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds genuinely non-redundant context – an approved account connection is required, and OAuth clients must run AlertForge's authorization flow with a specific setup URL. It doesn't say what the balance looks like (units, currency, or whether low balance affects subsequent 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?

Three sentences, none wasteful in isolation, but the ordering is backwards – the agent must read past account-setup boilerplate to learn what the tool does. Front-loading "Get the caller's current credit balance" would cost nothing and improve selection.

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 parameterless read with no output schema, the description covers the only real hazard: authorization state. It stops short of describing the returned value, which matters here because an agent likely needs the balance to decide whether to proceed with a paid generation call.

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

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

The tool takes zero parameters, so under the rubric the baseline is 4. The description correctly adds no parameter discussion, instead spending its words on the auth prerequisite, which is the only real precondition.

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 final sentence states a specific verb and resource: "Get the caller's current AlertForge credit balance." That is unambiguous and distinguishable from the sibling tools, which are all generation/planning/status operations. It loses a point only because the purpose sentence is buried after the auth boilerplate rather than front-loaded.

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

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

Usage is only implied: an agent can infer you'd check credits before kicking off expensive pack/render jobs, but the description never says so, nor does it state any condition or alternative. The setup instructions are prerequisite guidance rather than when-to-use 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?

Discloses the non-obvious truth that this 'get' call mutates state and is not idempotent, consistent with the annotations, and warns that callers must poll. It also explains link semantics (absolute signed URLs with no login required), link expiry, the extra 'tiles' stage for sheet packs, and what the tiles array contains. This goes well past what the annotations 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?

Dense and mostly earning its place, but the lead is the auth/setup sentence and URL rather than the core action, so the key behavior ('advances the pack and reports status') arrives third. Long, but almost every sentence carries operational information.

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

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

With no output schema, the description takes responsibility for return semantics: designPackage.status/imageUrl, designApproved, per-scene status, tiles array fields, and the complete flag. Combined with the polling loop instructions and auth prerequisite, an agent has everything needed to call it correctly in a loop.

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

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

The single parameter has 100% schema description coverage, so the schema already carries the meaning. The description adds the provenance note that projectId comes from create_design_sheet or create_overlay_pack, which is slightly beyond schema text but nothing more is needed for a one-parameter tool.

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 behavior: running ~15 seconds of rendering work and returning pack/scene status, including designPackage and tiles detail. It is far more than a restatement of the name. It does not, however, differentiate itself from closely-named siblings such as get_alert_pack_status, get_render_status, or get_style_sheet_character_edit_status, so an agent cannot fully infer which status tool applies to which pack family.

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

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

Gives concrete operating instructions: call repeatedly every few seconds until `complete` is true, and poll a design-sheet-only project until designPackage.status is 'ready' before calling approve_design_sheet. The prerequisite (approved AlertForge account connection, OAuth flow) is also spelled out. What is missing is routing guidance versus the sibling status 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false. The description repeats 'Read-only' and lists the information covered, but adds no further behavioral context such as return format or limitations. With annotations carrying the safety profile, this is adequate.

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 two concise sentences with no waste, front-loading the read-only nature and then listing the content scope. Every phrase adds useful information for selecting the 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?

For a zero-parameter informational tool with rich annotations and no output schema, the description provides sufficient scope to understand what will be returned. A minor gap is that it does not describe the return shape, but that is not critical for this simple informational 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?

The tool takes no parameters, so the baseline is 4 and there is no parameter semantics to document. The description appropriately does not attempt to describe inputs, which would be 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?

The description clearly identifies the resource as AlertForge product information and enumerates its scope: key features, supported streaming platforms, and OBS-ecosystem compatibility. It lacks an explicit verb such as 'returns' or 'gets', but the purpose is unambiguous and distinguishable from the creation and status 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?

The description implies usage by listing the information covered, but it does not explicitly state when to use this tool or name any alternatives. There are no similar informational siblings, so the implied context is adequate 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?

Annotations already declare readOnlyHint/idempotentHint/non-destructive, but the description adds genuinely new information: an approved AlertForge connection is required, OAuth clients should trigger the authorization flow, a setup URL, and that calls are free. It also discloses the return shape (status plus result video URL(s) when done), which is what a polling tool most needs to disclose.

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

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

Compact and mostly front-loaded, with the authentication prerequisite placed first where an agent will hit it before calling. The setup URL and OAuth instruction take up a full sentence of boilerplate, but they earn their place for a gated API.

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 describe returns — it does, naming status and result video URL(s) once finished. It stops short of enumerating possible status values or indicating whether the agent should re-poll, which is the main remaining gap for an async job 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?

Single parameter with 100% schema description coverage, so the schema already carries the semantics and the baseline is 3. The description only mildly extends it by noting the id can come from create_transparent_video or be 'any other render id'.

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

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

States a specific verb and resource (read-only poll of a render) and anchors it to create_transparent_video as the producer. The phrase 'or any other render id' slightly blurs the boundary with the sibling status tools (get_pack_status, get_alert_character_status, get_style_sheet_character_edit_status), so it falls short of fully distinguishing itself.

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?

Implied usage is clear (poll after create_transparent_video returns a renderId), and the auth prerequisite is stated. But there is no explicit guidance on when to prefer this over the sibling *_status tools for packs or characters, nor any polling cadence advice — the agent has to infer both.

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 non-readonly, open-world, and non-idempotent behavior; the description adds auth prerequisites, polling semantics, the completion return condition, and credit restoration on failed patches. This is substantial behavioral context beyond the structured fields.

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

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

The description is reasonably concise and no sentence is clearly wasted, but it opens with a multi-sentence auth setup before stating the tool action. Front-loading the operation would improve structure.

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 supplies the key return behavior: a revised full Style Sheet image when complete. It also covers auth, polling until completed or failed, and failed-patch credit restoration, which is enough for this single-parameter operation.

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

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

There is only one parameter, and schema description coverage is 100%, with the schema already explaining that editId comes from create_style_sheet_character_edit. The prose does not add parameter-level meaning beyond that baseline.

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

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

States a specific action and resource: advances the queued character edit, performs the server-side region patch, and returns the revised full Style Sheet image. The editId reference to create_style_sheet_character_edit helps distinguish it from creation and planning 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?

Tells the caller to call repeatedly until completed or failed and requires an approved AlertForge account with OAuth authorization. It does not explicitly exclude alternatives, but the usage context is clear from the edit lifecycle.

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 value beyond that: it is free to call, requires an approved connection with a specific authorization flow, and its data is derived live from billing config rather than hardcoded — meaning prices are authoritative and may change between 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?

Dense and mostly waste-free, with the enumerated return content and the sequencing instruction carrying real information. Minor ding: it front-loads the auth/setup paragraph and URL before stating what the tool actually does, so the core purpose is buried mid-description.

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 fully specifies what comes back (7 named alert types, two render tiers with silent/audio prices, character-generation price). Combined with the auth prerequisite, an agent has everything needed to call it and interpret results.

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

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

The tool takes zero parameters, so there is nothing to disambiguate and the baseline applies. The description does not need to explain any argument semantics and appropriately spends no words on 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 ('Lists the 7 AI Alert types') and enumerates the exact contents: alert types, two render tiers with credit prices (silent/with audio), and character-generation price. An agent can distinguish this catalog tool from pricing-unrelated siblings like get_product_info without opening a schema.

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

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

Explicitly sequences the tool: 'Call this before plan_alert_pack or generate_alert_character,' naming the two siblings that depend on it. It also states the precondition (approved AlertForge account connection) and the OAuth sign-in path, so the agent knows when it can and cannot 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds meaningful context beyond that: authentication requirements, setup URL, ordering, and the 20-item cap. It does not describe pagination or return shape, but adds solid behavioral context.

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

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

Three tight sentences with no filler. Authentication setup is front-loaded before the actual listing behavior, which is slightly less efficient than leading with the purpose, but still clear and appropriately sized.

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 with no output schema, the description covers what the agent needs: auth prerequisites, what is listed, ordering, and result cap. 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?

The tool takes zero parameters, so the baseline is 4. The description does not need to explain parameter semantics, and it appropriately focuses on authentication and result characteristics instead.

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

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

States a specific verb ('List') and resource ('caller's animated-overlay projects'), plus ordering ('most recently updated first') and a result limit ('up to 20'). No sibling tool performs the same listing operation, so the agent can select it with confidence.

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

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

Clearly establishes the prerequisite: an approved AlertForge account connection and OAuth flow for OAuth-aware clients. It does not explicitly name when-not-to-use alternatives, but no sibling list tool overlaps, so the usage context is still clear.

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. The description adds genuinely new behavioral context: an approved AlertForge account connection is required, OAuth clients must run the authorization flow and only ask the user to sign in and approve, plus a setup URL. The per-scene cap of 4 effects is a useful domain constraint not expressible in 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?

Three sentences, each carrying content: auth prerequisite, OAuth client behavior, purpose. The purpose statement is placed last behind auth boilerplate rather than front-loaded, which is a minor structural weakness for a reader scanning for what the tool does.

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 full annotation coverage, the description covers the gating prerequisites and the scope of results. It does not describe the shape of returned items (e.g., effect IDs vs display names), which would help an agent chain into a create call, but that is a small gap.

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

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

The tool takes zero parameters and schema coverage is 100%, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter-level value is added or needed.

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 final sentence gives a specific verb and resource ('List the particle overlay effects') and adds a constraint ('that can be Color-Dodge-blended onto a scene, max 4 per scene'). It is distinct from sibling list tools like list_scene_kinds or list_overlay_projects by naming the exact resource, though it never explicitly contrasts itself with them.

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

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

Usage is implied: call this to discover which particle effects are blendable onto a scene before compositing. There is no explicit when-not guidance and no named alternative among the many sibling list/create tools, so the agent must infer selection.

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

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

Annotations already declare readOnly/idempotent/closed-world, and the description adds real context beyond them: the approved-account requirement, the OAuth sign-in flow, a setup URL, and the exact shape of returned metadata including per-kind creatability reasons. That is exactly the value-add the description should provide on top of structured 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?

Auth requirements are front-loaded and the return-shape sentence is dense but informative. It runs long for a zero-parameter list tool, with billing/tile-slot detail that is close to the edge of what earns its place, but every clause carries actionable information.

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

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

No output schema exists, and the description compensates by describing the returned metadata fields and the tileInputs structure. Auth setup, creatability semantics, and the hand-off to plan_overlay_pack are all covered, so an agent can call it and use 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?

With zero parameters and 100% schema coverage there is nothing for the description to disambiguate, so it meets the baseline. It usefully clarifies that tileTexts is passed to plan_overlay_pack, not to this tool, preventing a parameter mix-up.

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 ('List every animated-overlay scene kind') and enumerates the metadata returned (label, animates, cam-frame, creatable, reason). It explicitly positions itself as the single source of truth for kind names, which separates it from sibling creation/planning 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?

Gives a clear directive ('never assume or hardcode a kind name') and routes the agent forward by naming plan_overlay_pack and the tileTexts override for sheet-pack kinds. Lacks an explicit 'when not to use' or prerequisite ordering against siblings like list_overlay_projects, but the usage context is clear.

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 the tool readOnlyHint=false, but the description says it operates "WITHOUT ... creating anything" even though it returns a single-use planId, which is a persisted artifact. That is a direct inconsistency with the non-read-only annotation; the auth, no-credit, and 24h expiry details are otherwise useful.

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 auth and cost, then usage and return behavior. However, the alerts subset explanation repeats schema text and makes the description longer 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?

For a complex, auth-gated planning tool with no output schema, the description covers credentials, setup, cost, planId lifetime/single-use, required character image, and next step. This is complete enough 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 schema already documents alerts omission/subset behavior, characterImageUrl, defaults, and enum tiers. The description reinforces the alerts semantics but adds no new parameter format or constraints beyond the schema, so baseline 3 is appropriate.

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

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

The description states the tool prices/proposes an AI Alert pack and distinguishes it from create_alert_pack by requiring a planId and confirmation step. It also specifies single vs full-pack behavior, so an agent can identify the tool's role among 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 an explicit call sequence: get a character via generate_alert_character, use list_alert_types for keys, show planId/cost to the user, and confirm before calling create_alert_pack. It also says to omit alerts for the full pack or provide only the desired subset.

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

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

Beyond the annotations, it discloses that no credits are spent, nothing is created, the planId expires in 24 hours and is single-use, and that the exact credit cost is returned and must be shown to the user. It also spells out the auth prerequisite with a setup URL and tells OAuth-aware clients to hand off to the authorization flow rather than asking for credentials.

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 auth requirement, then purpose, then the elicitation script, then the return/handoff — a sensible order. It is somewhat bloated by reproducing the three questions verbatim when the schema already carries the identical text, which costs roughly a third of the length without new information.

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

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

With no output schema, the description still specifies the return value (planId plus exact credit cost) and the planId's lifetime and single-use nature, plus the full pre/post condition chain. An agent has everything needed to call this and route the result 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 per-parameter meaning is already documented; the description nonetheless adds the ordering constraint across the three required briefs and the instruction to ask the user verbatim rather than inventing a theme. That is real semantic guidance beyond the schema, though the question wording itself is duplicated rather than extended.

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 — "prices the pack's shared Style Sheet (design sheet)" — and explicitly contrasts with the write sibling by saying it happens "WITHOUT spending any credits or creating anything." An agent can tell this apart from create_design_sheet and from the rendering/approval steps 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 position in the workflow ("The FIRST step for any new overlay pack"), the exact handoff ("then call create_design_sheet with this planId"), and the downstream blockers naming get_pack_status and approve_design_sheet. It also states a hard exclusion: scenes cannot be planned until the Style Sheet has rendered and been approved.

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: no credits are spent, nothing is created, the returned planId is single-use and valid 24 hours, and a missing approval yields a structured `design_sheet_required` error rather than a guessed theme. This resolves the tension with readOnlyHint=false by explaining the operation is a priced, non-mutating plan.

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

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

The content is valuable but delivered as one dense run-on with stacked em-dashes and parentheticals, making it hard to scan. It is front-loaded with account setup rather than the core plan-then-confirm contract, and the scene-kind enumeration late in the paragraph could be tightened or deferred to list_scene_kinds.

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 mutating-adjacent planning tool with no output schema: prerequisites, error semantics, the returned planId/cost/summary, the required user confirmation step, and the successor tool. No material gap remains.

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

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

Schema coverage is already 100%, so the description is not obligated to document parameters, but it adds real cross-reference value: projectId's provenance via approve_design_sheet, that visual identity comes entirely from the Style Sheet (no theme/reference input), and how `tileTexts` maps onto sheet-pack scene kinds with fixed slot counts.

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 ('normalizes and prices scenes') and immediately contrasts with the sibling that actually creates content: it does so 'WITHOUT spending any credits or creating anything'. An agent can distinguish plan_overlay_pack from create_overlay_pack 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?

Explicitly prescribes ordering — call list_scene_kinds first, obtain projectId from an approve_design_sheet-approved project, show the returned summary and cost to the user and get confirmation before calling create_overlay_pack. It also names the fallback (plan_design_sheet) when the prerequisite is missing, so the when/when-not decision is fully 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses the auth prerequisite (approved AlertForge account, OAuth flow), that calls are free and spend no credits, and that it returns a single-use 24-hour plan with exact cost. This is rich context the annotations do not 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 auth requirement and then proceeds to cost/workflow details; nearly every sentence earns its place. Slightly dense with setup URL and multiple clauses, but well structured.

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 the return (single-use 24-hour plan and exact cost) and the downstream confirmation step. For a 3-param planning tool it covers everything an agent needs 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 the schema already documents all three parameters. The description nonetheless deepens the mode semantics ('small change to the same character' vs 'replacing it while preserving the rest pixel-for-pixel'), adding marginal value over the schema's own enum 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?

States a specific action (prices a character-region change on an existing Style Sheet), clarifies it is a no-credit planning step, and distinguishes it from the sibling create_style_sheet_character_edit by name. An agent can tell it apart from plan_* siblings readily.

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

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

Explicitly routes mode=edit for small same-character changes versus mode=redesign for replacing the character while preserving the rest pixel-for-pixel, and gives the workflow rule: show the quote and obtain confirmation before calling create_style_sheet_character_edit.

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

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

Goes well past the annotations by disclosing that the call is free, spends no credits, and creates no artifact, plus that the returned planId is valid 24 hours and single-use. These are exactly the operational facts an agent needs before quoting a price to a user, and none of them are recoverable from the schema or 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?

A tight single paragraph where each sentence carries a distinct fact (auth, setup link, price-only semantics, return shape). It loses a point for leading with account/OAuth boilerplate ahead of the core purpose, pushing the actual 'what this does' later than ideal.

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 10 parameters, one nested object, no output schema, and a required-element handoff to a second tool, the description still covers prerequisites, cost behavior, return values (planId plus exact credit cost), and the next step. 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 90%, so nearly every parameter is already documented in the schema and baseline 3 applies. The description adds only the notion that credit cost depends on 'the chosen model tier', without explaining the tier/cost relationship or the reference-image pairing rules that the schema covers.

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 — prices a single transparent WebM video — and goes further to say what it is NOT (a plain animated clip, not an AI Alert, no chroma-plate, no OBS wiring). That explicitly separates it from create_alert_pack and from the sibling create_transparent_video, which actually renders.

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?

Spells out the prerequisite (approved AlertForge account connection, OAuth sign-in), the sequencing rule (show the returned cost and get confirmation before calling create_transparent_video), and the alternative path by naming the exact follow-up tool and the planId handoff. Nothing about when to call it 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.