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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds context they cannot carry: it explicitly says 'Uses no minutes' (a cost signal critical for an agent deciding whether to probe) and predicts failure behavior — an error explaining how to obtain a key when the key is missing or invalid.

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 sentences, zero padding, and the ordering directive is front-loaded ahead of the error-behavior note. Every clause carries actionable information for an agent.

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 compensates by naming the returned fields verbatim; the auth failure mode and the cost profile are also covered. For a parameterless read tool, nothing an agent needs to invoke it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the schema is fully closed (additionalProperties: false). A 4 is the appropriate ceiling because no parameter-level value can be added, though the implicit auth dependency (CUECAPS_API_KEY) is at least surfaced.

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 ('Reads the Cuecaps account behind CUECAPS_API_KEY') and enumerates exactly what comes back: plan, cloud minutes left, reset date, and whether agent captioning is included. That is far more precise than the sibling tools' names alone would allow an agent to infer.

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 call order: 'Call it before transcribe or caption_video to check the plan and minutes.' It names the exact siblings it gates and the condition (checking plan/minutes) that selects it, leaving nothing to inference.

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

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

Annotations only declare the mutation/scope profile; the description adds what an agent actually needs: the file is written next to the input, an existing file is never replaced, the video never leaves the machine, and the return payload includes the file, duration, engine, cloud minutes and a studio link. It also discloses the key-tier gating, which the annotations do not cover. Nothing contradicts the hints (destructiveHint=false is consistent with 'never replacing a file').

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

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

It is a single dense paragraph, but it is front-loaded with purpose and output behavior before prerequisites and alternatives. A couple of clauses are near-redundant (engine/cloud-minutes detail is repeated in the returned-fields list), slightly hurting scannability for a 13-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?

For a 13-parameter, multi-output rendering tool with no output schema, the description covers writes, collision handling, plan gating, privacy, return fields and sibling alternatives. An agent can invoke it correctly without further context.

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 eight parameters carry enums, so the schema already documents nearly everything. The description reinforces a few semantics (burned-in vs transparent overlay vs subtitles, out_path extension deciding format) but adds little beyond the schema text, 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?

The description opens with a specific verb and resource ('Captions a local video or audio file') and immediately names the renderer, the output formats, and the write location. It is clearly distinguishable from siblings: transcribe is named as the words-only path and studio_link as the manual-edit path.

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 exactly when to use alternatives ('Use transcribe when only the words are needed, and studio_link when the user wants to edit by hand or has no key') and adds prerequisites (Creator or Pro key, Pro for 1440p/4K). An agent has no guesswork about 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false. The description adds genuinely new behavioral facts beyond those: the list is fixed and requires no key, and it discloses the shape of each entry. It stops short of noting ordering or caching guarantees, so not 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?

Three short sentences: what it returns, how the result is consumed, and when to call it. No filler, and the actionable trigger is placed last where it reads as the decision rule.

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 enumerating the fields of each returned style (id, name, appearance) and explaining what the id is for. Nothing needed to invoke or interpret this zero-argument read tool 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 correctly implies no filtering or selection arguments exist by framing the result as a complete fixed list of 10.

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?

Specific verb plus resource ('Lists the 10 Cuecaps caption styles') with the exact payload spelled out (id, name, appearance). It also disambiguates by naming the downstream tools that consume the returned id (caption_video, studio_link), so an agent can place it relative to 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?

Explicit trigger conditions: 'Call it when the user hasn't picked a style or asks what the styles look like.' That is a concrete when-to-use rule tied to the downstream caption_video/studio_link flow, 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 declare readOnlyHint, idempotentHint and destructiveHint=false, but the description adds context the annotations cannot: it creates nothing server-side, needs no API key, and therefore works on Free plans. It also explains the handoff — the user drops in the video, fixes words, exports in the browser. It stops short of saying whether the URL is stateless or expires, which is the one real gap.

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

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

Front-loads the return value, then the no-key/no-plan-requirement guarantee, then the when-to-use and the alternative. Every sentence does work, though the single dense paragraph runs slightly long and could be split for scannability.

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?

Six optional parameters, no output schema, no annotations covering semantics — yet the description states what is returned (a URL), that nothing is persisted, that no credentials are needed, and what the user does next. That is everything an agent needs to call it correctly and set expectations.

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% with enums and per-parameter descriptions plus hints like 'list_styles shows how each one looks', so the schema carries the semantics. The description only gestures at them collectively as 'these caption settings' and adds no format or default guidance beyond that. Baseline 3 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?

States a specific verb and resource — returns a URL to the Cuecaps studio pre-loaded with these caption settings — and immediately contrasts it with caption_video, which makes the file directly. An agent can distinguish it from every 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 routing rules: use when the user wants to edit by hand, has no Creator/Pro key, or the file isn't on this machine; use caption_video instead to produce the file. Both positive selection criteria and the named alternative are given, leaving nothing to inference.

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

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

Goes well beyond the annotations: discloses that no file is written, that a Creator or Pro key is required, that cloud mode bills plan minutes and sends only compressed audio deleted after transcription, and that device mode downloads a 132 MB model on first run. These are auth, cost, and privacy facts the readOnlyHint/destructiveHint flags 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 outcome and return shape, then the exclusion, then the prerequisites and engine tradeoffs — every sentence earns its place. Minor redundancy: the cloud/device engine explanation partly repeats the engine schema description, and the sentences are dense enough that a reader must parse carefully.

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 contract itself and does so (timestamped words, SRT text, engine). Auth requirement, cost model, file-writing behavior, and the alternative tool are all covered, leaving nothing an agent needs 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 coverage is already 100%, but the description still adds value the schema lacks: the default resolution rule for engine ('picks cloud when the minutes left cover the file, else device') and the privacy/consumption consequences of cloud mode. This is behavior an agent would otherwise have to guess at call time.

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 ('Transcribes a local video or audio file') and immediately defines the return payload (words with start/end seconds, SRT text, engine used). It explicitly names the sibling it is not (caption_video) so an agent can route between them 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 excludes the captioning case: 'use caption_video when the user wants a captioned video, an overlay or a subtitle file.' It also gives selection guidance for the engine parameter, including the exact default heuristic when the parameter is unset, so the agent knows it can omit it.

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