RecordHTML

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds context beyond that: exactly what is destroyed (original plus crop/trim files), that the recording remains in history with status 'deleted', and that re-deletion is a no-op. It does not mention auth requirements or immediate vs. eventual file removal, keeping it at a 4.

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, each carrying distinct information: what gets deleted, what remains, and irreversibility/idempotency. Front-loaded with the destructive effect and zero filler.

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

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

With an output schema present and annotations covering safety semantics, the description supplies everything else an agent needs: the precise effect on files versus metadata, irreversibility, and idempotent behavior. 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?

Only one parameter with 100% schema description coverage, and the schema already explains where the id comes from (record_html or list_recordings). The description adds no parameter detail but the baseline for a single fully-documented param is high.

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 ('Delete a recording') and immediately narrows scope to the video files (original, crop, trim) while clarifying the record itself persists. This clearly separates it from siblings like get_recording, list_recordings, and record_html, which are all read-oriented.

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 makes the destructive nature and idempotency clear, which helps the agent decide whether to call it at all, but it never names an alternative (e.g., a soft-delete or restore path) or states when not to use it. Usage is implied rather than guided.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description is consistent with that. It adds real value by naming the failure categories returned (invalidIssues, limitIssues, capacity.reasons) and the quota/usage reporting, so the agent knows this is a side-effect-free preview that surfaces account limits. It does not say whether any network fetch of the url/html still occurs, which would matter for a validation call.

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

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

Three short sentences, front-loaded with the side-effect-free promise, then the argument relationship, then the return contents. Zero 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 22-parameter validation tool this covers what matters: parity with record_html, the absence of quota cost, and the shape of the useful part of the response. An output schema exists, so the return-value listing is a bonus rather than a necessity.

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% across 22 parameters, so the schema fully documents constraints and enums. The description adds only the useful fact that the argument set is identical to record_html; it gives no semantics of its own for any parameter, which is acceptable at baseline 3.

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

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

States a specific verb and resource ("Check a recording request") and immediately distinguishes it from the real thing by contrasting it with record_html, whose arguments it mirrors. An agent can tell it apart 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?

Makes the core use case clear: validate a request without recording or consuming quota, implying it should be called before record_html. It stops short of an explicit "use this before record_html; use record_html when you want the actual file" routing statement, but the argument-parity note carries the intent.

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 that this is a read-only, non-open-world tool. The description adds valuable behavioral detail beyond annotations: the video link is signed and valid for one hour, and waitSec waits for completion up to 45 seconds. It does not add much about auth or failure behavior, but the main traits are disclosed.

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 sentences with no waste. The return contents are front-loaded, followed by the waitSec behavior and the practical use cases.

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 tool has annotations, full schema coverage, and an output schema, and the description still provides enough context to call it correctly. The main behaviors an agent needs, link freshness, waiting, and continuation after record_html, are all covered.

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 meaning for waitSec by explaining that it waits for a queued or running recording to finish and caps at 45 seconds. It also contextualizes the id indirectly through record_html continuation, though the schema already documents the id source.

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 and enumerates what is returned: status, report, and a fresh signed video link. It also distinguishes the continuation use case from record_html, so an agent can tell why this tool exists 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?

Explicitly says to use it after record_html returns before the video is ready and to refresh an expired link. It also explains when waitSec applies, namely for queued or running recordings, which gives clear invocation guidance.

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

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

Annotations already declare readOnlyHint=true, and the description adds real value: default page size of 10, newest-first ordering, and that video links are omitted from results. It does not discuss the status filter's behavior beyond the schema, but the safety profile and output shape are well covered.

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; scope, fields, exclusion, alternative and pagination are all front-loaded 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?

An output schema exists, yet the description still names the returned fields and the notable exclusion, plus pagination mechanics, leaving nothing an agent needs missing.

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

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

Schema coverage is 100%, so limit, cursor and status are fully documented in the schema. The description only echoes the default page size and cursor chaining, adding little beyond structured fields, which matches the baseline 3.

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

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

States a specific verb and resource (List your recordings) plus sort order (newest first) and the fields returned, so an agent knows exactly what it gets. It explicitly distinguishes itself from get_recording for video links.

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?

Routes the agent to get_recording when video links are needed and explains how to continue with nextCursor. It does not say when to prefer this over siblings like estimate_recording, but for a list endpoint the guidance 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 already flag openWorldHint=true and non-readOnly, but the description goes well beyond them: it discloses the 10-minute idempotent-replay window, that failed recordings are never reused, that the signed video.url expires in 1 hour while pageUrl requires sign-in, that the job keeps running past waitSec, and that account-level limits (length/size/fps/concurrency/day) apply. Minor tension with idempotentHint=false, but the text clarifies the nuances 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?

Long, but justified by 24 parameters and organized under front-loaded headers (Input, Waiting, Retries, Trim markers, Links, Limits). Some redundancy with the schema remains — waitSec's default 45 and 'recording keeps going' are stated in both places, and the trim-marker code sample is verbose.

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 open-world operation with nested objects, enums, and a 24-parameter schema, the description covers the full call lifecycle: input selection, sizing, waiting/polling, retry semantics, marker-based trimming, link expiry, and failure handling. An output schema exists, so not explaining return shapes is appropriate.

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 nonetheless adds semantics the schema cannot: typical creative dimensions (300×250, 728×90, 1080×1920), what durationSec means when trim_end() fires, that revision exists specifically to re-record a changed creative behind the same url, and the sync='markers' failure mode. That is real meaning beyond the field docs.

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 states a specific verb and resource ('Record a web page or HTML5 creative') plus the output formats (MP4/WebM/GIF) and the return value (a video link). It is clearly distinguishable from siblings: get_recording waits on an existing job, estimate_recording checks limits without recording, list/delete manage recordings.

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 the agent to alternatives: 'Call get_recording with its id and waitSec ... don't call record_html again for it', and 'estimate_recording checks a request without recording'. It also states when-not conditions (localhost/private networks unreachable, pass url or html but not both) and the retry/replacement rules for changed creatives.

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