ffpipe — video conversion, probe & frames

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

The description adds substantial behavioral detail beyond annotations: async queueing, upload behavior, payment requirement ($0.02 via x402), retryVoucher alternative, 24-hour download window, and the need to poll until finished/error. Since annotations only give generic read/write/side-effect flags, the description carries the burden, and it does so thoroughly.

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?

Six dense clauses are packed with essential owner: function, source/upload modes, dimensions, output format, polling, retention, cost, and payment alternatives. No filler; the main operation is frontloaded.

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

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

Given no output schema, the description compensates by specifying return fields, statuses, polling relationship, upload target, timeout/download window, and cost. This is complete enough for an agent to invoke the tool successfully without external documentation.

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 schema already explains every parameter, including defaults and constraints. The description repeats and slightly recontextualizes maxWidth/maxHeight defaults, the sourceUrl fetch behavior, and the upload path, but it does not materially add per-parameter meaning beyond schema; it mainly explains the overall workflow and payment.

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 by naming the operation — queue asynchronous video conversion — and states exact output format and scope (fetches sourceUrl or upload, converts to MP4, scales to fit dimensions). This distinguishes it from siblings like extract_frames, probe_media, and get_job_status, which are clearly different operations.

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 provides strong context for when the tool should be used: it is the entry point for conversion, then the caller polls get_job_status with the returned jobId and token. It also clearly distinguishes the sourceUrl vs upload:true paths. It does not explicitly say when not to use it relative to extract_frames or probe_media, or name those alternatives, so it stops one point short of fully explicit deferral.

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 provide basic hints (readOnlyHint=false, destructiveHint=false). The description goes far beyond, disclosing async behavior, upload flow with charging at acceptance, 24-hour download window, failure cases, and the manifest structure. It explains the retryVoucher mechanism and x402 payment. This is exemplary transparency.

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

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

The description is long but well-structured, front-loading purpose and mode requirement, then covering output, edge cases, and payment. Every sentence adds value, though some redundancy exists (e.g., 'Up to 1000 frames' repeats maxFrames schema). It could be slightly trimmed but is efficiently organized.

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

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

Given the tool's complexity (15 params, async, payment, no output schema), the description covers all essentials: input methods, output manifest, mode semantics, limits, failure modes, payment, and even a single-frame shortcut. 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?

Schema covers 100% of parameters with descriptions, so baseline is 3. The description adds relational context: why mode is required ('no default because every candidate implies a rate you did not ask for'), how all/interval can exceed limits, and the upload parameter's detailed flow. It enriches understanding without repeating 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?

The description clearly states the tool's purpose: 'Queue an asynchronous frame extraction - the tool to reach for when you need to SEE a video.' It specifies the verb, resource, and even the output format (manifest of frames). It distinguishes itself from siblings by explicitly positioning itself as the go-to for seeing video, contrasting with probe_media for diagnostics and convert_video for conversions.

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 explicit when-to-use guidance: 'the tool to reach for when you need to SEE a video.' It also covers when not to use it: 'Unreadable input, audio-only files and still images FAIL here (probe_media diagnoses those).' It advises on mode selection for long sources ('prefer interval, evenly_spaced or timestamps') and even suggests alternative modes for single frames. This is comprehensive.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value beyond these by stating it is free, takes no input, reads the account behind the credential, never presents a payment challenge, and details the error case for anonymous callers. No contradiction with annotations. The extra context about permissions and error handling is helpful.

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 well-structured, starting with the key fact 'Free' and then the core purpose. It is about 3-4 sentences long, each sentence adding distinct value (balance, cost breakdown, usage guidance, error case). It is not overly verbose, but could be slightly tighter by removing redundant phrasing like 'connected to' and 'connected with'. Still, it is efficient and clear.

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

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

Given no output schema, the description fully explains what the tool returns: credit balance, credit worth, operation costs, monthly free allowance, and whether a card is on file. It also mentions the account page name for top-ups. The error case for anonymous callers is covered. The tool has no parameters and is simple, but the description leaves no gaps for an AI agent to understand its behavior and output.

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

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

The tool has zero parameters, so description cannot add parameter-level meaning. According to guidelines, baseline is 4 for 0 params. The description correctly notes 'Takes no input: it reads the account behind the credential your client already connected with.' This is sufficient and does not repeat schema information.

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

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

The description clearly states it reports the credit balance and related financial details (credit worth, operation costs, free allowance, card on file). It is a unique tool among siblings (convert_video, extract_frames, etc.) as it focuses on account balance and usage limits, not media processing. The verb 'reports' and resource 'credit balance' are specific and unambiguous.

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

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

The description explicitly advises calling this tool to find out how much work can be queued and to get the top-up link. It distinguishes between paid account holders (who have balance) and anonymous callers (who get unauthorized error). It does not explicitly name alternatives, but the context is clear and the sibling tools are unrelated (e.g., convert_video, get_job_status). The guidance is practical and sufficient for an AI agent to decide when to use 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 signal readOnlyHint, idempotentHint, and destructiveHint. The description goes far beyond by detailing the status lifecycle (including awaiting_upload, queued, finished, error), explaining what each state returns (e.g., uploadExpiresAt, resultUrl, retryVoucher), and even noting that bad tokens vs unknown jobIds both return not_found deliberately. No contradictions.

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 a single dense paragraph that packs a lot of information without wasted words. It front-loads the purpose and token requirement, then efficiently covers the status lifecycle. While it's somewhat long, every sentence adds value, so it earns a high score for conciseness given the complexity.

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

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

Despite no output schema, the description fully documents what the response contains for each status (uploadExpiresAt, resultUrl, thumbnailUrl, durationMs, retryVoucher), including the 24-hour free re-download window and redirect behavior. It also covers edge cases like awaiting_upload not having an uploadUrl. For a tool with this complexity, the description is complete.

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% with descriptions for jobId and token. The description adds critical context: it explains that the token is the 't' query parameter of the statusUrl and warns that the token cannot be regenerated, which is essential for correct usage and not evident from the schema alone.

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 explicitly states it is a 'Free status lookup for a job accepted by' and lists three specific sibling tools (convert_video, probe_media, extract_frames), making the verb+resource highly specific and clearly distinguishing it from other 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?

The description explains when to use the tool (after job acceptance), what is required (ownership token from statusUrl), and provides critical guidance on storing the token because it cannot be regenerated. It does not explicitly state when not to use it, but the context is clear enough for an agent to decide.

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 provide minimal behavioral hints (none are true), so the description carries the full burden. It explicitly states this is free, unauthenticated, one-way, returns only an acknowledgment, and creates no job. This provides comprehensive transparency about the tool's behavior 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?

The description is densely informative with every sentence adding value: it explains the why, when, and how, plus constraints and side effects. It front-loads the core intent and progressively adds detail, achieving high conciseness without waste at 4 sentences.

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

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

Given the tool's simplicity (4 params, no output schema, no nesting) and the rich annotations coverage, the description fully explains the tool's purpose, constraints, and outcomes. No gaps remain—the agent can correctly select and invoke it without additional information.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by further contextualizing jobId as 'not checked and not required' and describing the message length limit. It reinforces the parameter meanings from the schema, though it doesn't add entirely new semantics, so 4 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 clearly states the tool is for requesting capabilities, reporting problems, or giving feedback. It uses specific verbs like 'tell us what you needed' and 'report a problem,' and distinguishes it from sibling tools like convert_video or extract_frames by positioning it as a non-operation feedback mechanism.

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 explicitly explains when to use this tool instead of others: when ffpipe lacks a desired operation, for bug reports, or other feedback. It also tells users to include jobId for context and contact for a reply, providing very clear usage guidance with no ambiguity.

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 destructiveHint=false. The description adds significant behavioral context: async nature (polling required), result lifetime (24 hours), error handling (undecodable files return SUCCESS with diagnosis), payment and voucher mechanics, and upload flow details. This goes well beyond 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?

The description is comprehensive but verbose, mixing core purpose, parameter details, pricing, and result format in a dense block. While every sentence adds value, it could be better structured (e.g., separate sections for usage, parameters, output, pricing). It is adequate but not optimally concise.

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

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

Given the complexity (13 parameters, no output schema), the description covers return format (including the summary object), async polling, error handling, pricing, and parameter nuances (e.g., upload flow, readIntervals syntax). No gaps are apparent; the agent has enough context to invoke the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining output structure (ffpipe_summary block), upload process, readIntervals syntax, and the meaning of display_width/height. These clarifications are not present in the schema and aid correct parameter usage.

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

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

The description clearly states the tool's purpose: 'Queue an asynchronous media inspection: fetches sourceUrl ... and returns its technical metadata as a downloadable file.' It uses a specific verb ('inspect'), specifies the resource (media via URL or upload), and distinguishes itself from sibling tools like convert_video or extract_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?

The description implicitly guides when to use this tool (for media inspection to get technical metadata) and provides detailed usage context such as payment ($0.01 via x402 or retryVoucher), async polling via get_job_status, and result expiration. It does not explicitly state when not to use it or name alternatives, but the context is clear enough for an agent.

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