GetVideoFrames

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

Goes well beyond the annotations by disclosing auth requirements (no API key), cost (no credits), rate limiting ('Limited per IP'), input limits (public video, max 15 minutes), output shape (6 JPGs, max 640px), and a privacy quirk (source URL is not returned). The idempotentHint is not echoed, but the added operational context is substantial.

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, each carrying a distinct fact (cost/auth, output specs and limits, follow-up call). The most decision-relevant information — free, no key — is 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?

With no output schema, the description carries the return-value burden and does so: it says an id is returned and how to use it, and warns the source URL is not returned. It omits expected timing or how long the demo result persists, which would fully close the loop for an async flow.

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

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

Schema coverage is 100% so the 'url' parameter is already documented, but the description adds a real constraint on its valid domain — the video must be public and no longer than 15 minutes. That is meaningful input guidance beyond the schema's 'Public video URL'.

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 ('Extracts 6 evenly spaced JPG frames ... from a public video') plus the demo scope, which cleanly separates it from getvideoframes_create_job. An agent can tell this is the no-credential sandbox path 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 clear selection context: free/public preview, no API key, no credits, IP-limited, 15-minute cap, and names the follow-up call (getvideoframes_get_demo with the returned id). It stops short of explicitly saying when to switch to create_job (e.g., long videos, production use), leaving that 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 mark it as non-read-only, non-idempotent and open-world; the description goes well beyond by disclosing the credit cost model ('1 credit = 1 minute of processed video'), that failures are not charged, that wait=true blocks up to 50s, the 300-frame ZIP threshold, and the free-plan resolution cap.

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

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

Front-loads the action and the cost caveat, then uses tight bullets for modes, defaults and workflow. Every sentence carries distinct information with no restatement of the name or 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 14-parameter async job tool with no output schema, the description covers cost, delivery format, blocking behavior, polling path, plan limits, and the platform boundary. An agent has everything needed to invoke it and interpret the immediate return.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that exactly one mode applies, how mode is inferred from count/timestamps, and the defaults for format, resolution and delivery that the schema states only tersely.

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 ('Queue a frame extraction') and immediately scopes it to 'a public video URL'. It is clearly distinguishable from siblings like getvideoframes_get_job or getvideoframes_list_jobs, and the supported URL list removes ambiguity about inputs.

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 the follow-up workflow explicitly ('Returns immediately unless wait=true ... Then poll getvideoframes_get_job') and routes non-frame needs elsewhere ('If the user also wants a transcript ... connect GetTranscribe'). It does not, however, distinguish this tool from the sibling getvideoframes_render_frames or getvideoframes_create_demo, so the routing among near-neighbors is partial.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: frame URLs are only present when the demo has completed and has not expired, which the agent needs to interpret a sparse result. It stops short of describing the expired/error case.

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, zero filler, front-loaded with the action and then the conditional result and the follow-up call. Every sentence earns its place.

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

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

With no output schema, the description usefully explains the conditional presence of frame URLs and points to the rendering step, which is the key thing an agent must know. It could be slightly more complete about what happens when the demo has expired or failed, but it is adequate for this simple one-parameter read.

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

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

Schema description coverage is 100% and there is a single, fully documented uuid parameter that already states it comes from getvideoframes_create_demo. The description adds no format or constraint detail beyond the schema, 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 ('Read a public demo job by id'), and the 'public demo' qualifier implicitly separates it from the sibling getvideoframes_get_job and getvideoframes_create_demo. 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?

Explicitly chains to the sibling: 'Then call getvideoframes_render_frames with source=demo and the same id to show the filmstrip.' It tells the agent both what to do with the result and which alternative tool completes the workflow.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds real context beyond that: the prerequisite of a 'completed job', the returned content shape (image block, base64, mimeType values), and the warning that a URL is not a substitute for pixels.

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 paragraphs, front-loaded with the core action and return shape, then usage, then sibling disambiguation. Every sentence carries a distinct piece of information; 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?

With no output schema, the description compensates by describing the returned image content block and its fields, and it covers prerequisites and alternatives. An agent has everything needed to call and interpret the result.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds a genuinely non-obvious clarification: frame_index is 'frames[].index, not a position in the list', plus the source of the id ('from getvideoframes_get_job'). That is value beyond the schema text.

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

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

Specific verb+resource: 'Download one frame from a completed job and return the image bytes as MCP image content'. It explicitly positions itself against siblings getvideoframes_get_job (URLs/metadata) and getvideoframes_render_frames (filmstrip), so an agent can route 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?

States when to use it ('user asks what a frame shows, to compare frames, or to analyze a still') and names the two alternative tools with the conditions under which they, not this tool, apply. Nothing is left to inference.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context on top: the full status lifecycle, the 50-second blocking behavior, and the fact that URLs are presigned and expire. That expiry/blocking detail is not derivable from 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?

Front-loaded with the core action, followed by a compact status list and then the routing sentences. No filler; 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?

No output schema exists, but the description compensates by describing what a completed response contains (frame list with download URLs). Combined with the status enumeration and sibling routing, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds usage context for wait (blocking only matters while the job is running) and reinforces id reuse across sibling calls, going modestly beyond the schema text.

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

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

States a specific verb and resource ("Read one job by id") and immediately scopes the payload (presigned frame URLs, only while completed and unexpired). It is clearly distinguishable from list_jobs, get_frame, and render_frames.

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: render_frames with the same id for the filmstrip, get_frame with the same id plus frame index for pixels, and wait=true when the job is still running. When-to-use and alternatives are all named.

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/openWorld=false, so the safety profile is covered. The description adds genuinely new behavioral context: that the endpoint is public and requires no API key, which is an access/auth trait the annotations do not 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?

Three short sentences, front-loaded with the access fact and the payload summary. Every sentence carries information an agent would use (auth-free, contents, credit conversion) 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?

There is no output schema, so the description compensates by listing the exact fields the response contains plus the credit-to-video/frames conversion rate. For a parameterless, read-only pricing endpoint, nothing needed to invoke or interpret it is missing.

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

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

The tool takes zero parameters and schema coverage is 100%, so the baseline is 4 by rule. There is nothing further for the description to clarify about inputs.

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+resource: it returns the public price list, and it enumerates exactly what that contains (credit definition, free allowance, credit pack, named plans). This is unmistakably distinct from the job/usage siblings, which an agent can tell apart 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?

It states the key access condition ("No API key"), which implicitly tells the agent it can call this without authentication. However, it never contrasts itself against getvideoframes_get_usage or explains when an agent should fetch pricing versus usage, so usage guidance remains implied rather than 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 readOnly/idempotent/non-destructive, so the safety bar is low. The description adds genuine domain context: plan credits reset per period, pack credits never expire, and free accounts get 60 credits/month — useful behavioral detail beyond the annotations.

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

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

Front-loads the return contents, then the usage trigger, then the credit-policy detail. Every clause earns its place with no 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?

With no output schema, the description compensates by enumerating what is returned (plan, balance, limits, ledger) and explains the credit semantics. An agent has everything needed 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?

Only one optional parameter with 100% schema coverage; the schema itself explains the gvf_live_ key and when to omit it. The description adds nothing about parameters, 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: reads the caller's plan, credit balance, limits, and recent ledger. This clearly distinguishes it from siblings like getvideoframes_create_job and getvideoframes_get_pricing 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 states when to use it: 'Call this before creating a job if you need to know whether credits remain.' It ties usage to a concrete precondition but does not contrast with the get_pricing sibling, which an agent might confuse it with.

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 traits. The description adds meaningful output behavior beyond annotations: results are ordered newest first and history rows omit frame URLs. It does not mention pagination behavior or auth nuances, but the schema covers those.

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 with zero waste. The ordering constraint is front-loaded and the sibling routing is placed immediately after the key output limitation, making it easy to scan.

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 needn't detail return shapes; it still discloses the critical output limitation (no frame URLs in history rows). Annotations cover safety and schema covers all parameters, so nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so all four parameters (skip, limit, status, api_key) are fully documented in the schema. The description adds no parameter-level syntax or format details beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb (List) and resource (caller's jobs) with ordering ('newest first'), and explicitly differentiates from the sibling getvideoframes_get_job by noting history rows lack frame URLs. An agent can distinguish this from get_job 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?

Provides clear routing guidance: use this to list jobs, and call getvideoframes_get_job when frame URLs are needed. However, it does not state broader when-to-use context (e.g., monitoring progress, checking status) or any exclusions beyond the frame URL case.

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

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

Annotations cover the safety profile (readOnly/idempotent/non-destructive), and the description adds behavior those annotations cannot: the ChatGPT-specific side effect that opening a frame uploads the JPEG to ChatGPT for the next reply, plus the source=demo routing. That is exactly the kind of context beyond structured fields the dimension rewards.

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 earns its place: prerequisite, id binding, source guidance, exclusion, and the ChatGPT upload behavior are all front-loaded and non-redundant.

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

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

With an output schema present, return values need not be described. The description covers when to call, what id to pass, when not to call, and the client-specific side effect, which is complete for this tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by tying the id parameter to the prior get_job/get_demo call ('Pass that same id') and clarifying source=demo usage, which is more than the enum alone conveys.

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

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

States a specific verb+resource ('Render one ChatGPT filmstrip card for a completed extraction') and explicitly distinguishes itself from sibling getvideoframes_get_frame, which 'still returns the image bytes for other clients.' An agent can separate these two without opening either schema.

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

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

Gives explicit prerequisites ('Call this after getvideoframes_get_job or getvideoframes_get_demo returns status completed'), an exclusion ('Do not call this while the job is queued or processing'), and the alternative for other clients (get_frame). Nothing is left to inference.

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