ffpipe — video conversion, probe & frames

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

Description fully discloses async behavior, payment details ($0.05, x402 or retryVoucher), upload workflow (PUT bytes before deadline, no refund on abandoned upload), result structure, polling via get_job_status, and 24-hour download window. Annotations only provide readOnlyHint=false, idempotentHint=false, destructiveHint=false, which are consistent; description adds all critical behavioral context 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?

Description is well-structured and efficient, covering purpose, workflow, constraints, and payment in a few sentences. Slightly dense but not verbose; all information is necessary. Could be slightly more scannable with bullet points, but still effective.

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?

Description is complete for a complex tool with 5 parameters, no output schema, and rich behavioral context. It explains async lifecycle, payment, upload vs source, dimension limits, polling mechanism, and error handling. Leaves no major gaps for agent 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% with detailed descriptions, but the tool description adds high-level context: default dimensions (1920x1080), cap (4096), upload vs sourceUrl choice, payment via voucher, and the overall workflow. Description enhances understanding beyond individual parameter 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?

Description clearly states the tool queues an asynchronous video conversion, specifies source URL or upload mode, output format (MP4), scaling constraints with defaults and cap, and payment model. It distinguishes itself from siblings by covering conversion, not extraction, probing, or status polling.

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?

Description explicitly covers when to use (to convert video), async workflow (queue then poll), and mentions sibling tool get_job_status for polling. Includes constraints (max 100 MiB, no IP literals, etc.) and alternatives for payment (x402 vs retryVoucher). Does not list explicit exclusion scenarios, but the detailed async flow and payment options provide strong 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 provide no readonly, destructive, or idempotent hints, but the description fully compensates by detailing the async queue behavior, upload workflow, payment via x402 or retryVoucher, 24-hour download window, 1000-frame limit, and failure conditions (exceeding limit, unreadable input, audio-only, still images). This is far beyond what annotations offer.

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 front-loaded with the purpose, but it runs long (multi-sentence paragraph). Every sentence adds value, but the length could be slightly trimmed for quicker scanning. Still, it is well-organized and avoids redundancy.

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 queue, payment, upload options), the description covers all critical aspects: behavior, failure modes, pricing, voucher usage, and manifest format. No output schema exists, so the description's explanation of the result URL content is essential and well-handled.

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. However, the description adds significant value by explaining the absence of a default for mode (avoids assuming a rate), clarifying the upload flow (status awaiting_upload), and describing the manifest structure (resultUrl JSON). It also warns about the exact-one constraint between sourceUrl and upload, which is implicit in the schema. It does not explain every parameter in prose but compensates through rich context.

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 queues asynchronous frame extraction for video, specifying output formats and the core requirement to 'SEE a video'. It is distinct from siblings like convert_video (which likely transforms format) and probe_media (which diagnoses files).

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 says when to use this tool (when you need to see a video), warns against using 'all'/'interval' on long sources, suggests preferring interval/evenly_spaced/timestamps, and mentions probe_media for diagnosing unreadable inputs. It also clarifies the upload vs sourceUrl distinction.

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.