Weftly

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

With no annotations, the description carries the full burden and does so richly: two mandatory no-default choices, the two-call pay-then-process flow, pricing model, batch caps (5 clips / 30min / profile-specific ceilings), auto-refund on failed jobs, retry semantics, loudness normalization, and storage TTLs. This is unusually complete behavioral disclosure.

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?

Purpose and the sibling contrast are front-loaded, and the density is largely functional for a complex 10-param tool. It is nonetheless a very long single blob with some repetition (payment re-explained, well-known URL referenced twice), which costs it a point.

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?

Complete for a no-output-schema, no-annotation mutation tool: return artifacts (role names like clip-1-video, clips-manifest, clip-srt/clip-words), payment recovery, failure/refund behavior, and constraints are all spelled out. Nothing an agent needs to invoke and 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?

Schema coverage is 0% across 10 params, yet the description explains nearly all of them: orientation semantics, output behavior, profile/subject options with defaults and rejection rules, include_transcript applicability, captions default, and the clips object shape and the job_id/source_job_id/payment_credential roles in the flow.

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 ('Cut one or more clips from any prior video job') and immediately scopes it to parent jobs, explicitly contrasting with the sibling `clips_from_video`. An agent can distinguish the 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 an explicit selection rule versus the alternative ('use this tool whenever a video job already exists'), names the sibling it is not, and even routes to the REST API's `extract_vertical_clip` when `manual`/`subject_id` are needed. When-to-use is fully disambiguated.

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?

No annotations are provided, so the description carries the full burden — and it does: payment model (card-only, Stripe hold up to $4.50, charged once at the end), the two-call resume protocol, and the critical warning that re-calling without job_id authorizes a SECOND hold. It also discloses that horizontal does not publish (publishing is publish_to_youtube), preventing a realistic misuse.

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?

Purpose and routing lead the description, and nearly every sentence carries operational weight (payment shape, resume protocol, orientation choice). It is nonetheless a dense block that revisits the payment/retry theme more than once, so it is longer than strictly necessary.

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, and the description fills that gap: it describes the first-call return ({job_id, status: 'awaiting_payment', checkout_url}), the second-call return (checkout_url or upload step), and the final clips-manifest output alongside transcript and candidates. An agent has everything needed to drive the full chain.

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 0% across 8 parameters, so the description must compensate, and it explains most of them well: query (switches discovery to content matching), filename + content_type (video only), job_id (same-id resume semantics), orientation (vertical vs horizontal and their caption defaults), and captions. It gives no meaning for thread_id or for the job_type enum (clips_from_video vs clips_youtube), which the schema lists as required.

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 opening sentence states a specific verb and resource ('Find clips in a video AND cut up to 5 of them, under ONE payment') and immediately names itself as the alternative to the find_clips + clips_from_job sequence. An agent can distinguish it from both siblings 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?

Explicit when-to-use ('prefer it whenever the user wants clips delivered end-to-end from a video they have not yet uploaded'), explicit when-NOT ('a wallet-only MPP agent should NOT call this tool — call find_clips then clips_from_job instead'), plus a tie-break rule for the ambiguous orientation case. This is as complete as usage guidance gets.

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?

With no annotations provided, the description carries the full burden. It discloses that the tool verifies file presence in storage and job payment, and that it returns status 'processing'. This covers key behavioral aspects, though it omits error scenarios or authentication requirements.

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 two concise sentences, front-loaded with the primary action and immediately providing necessary context on preconditions and next steps. Every sentence adds value with no unnecessary wording.

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 simple tool with one parameter and no output schema, the description provides sufficient context: it explains the upload prerequisite, the verification behavior, the returned status, and how to track progress. It lacks explicit failure handling but is otherwise 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?

The schema fully describes job_id as 'The job_id returned from a previous transcribe or summarize call.' The description does not add extra semantic detail beyond that, but since schema coverage is 100%, the baseline of 3 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's function: 'Confirm that the file has been uploaded (via HTTP PUT to the upload_url from transcribe or summarize) and start processing.' This specifies a concrete verb and resource, and distinguishes it from siblings like transcribe/summarize (which initiate jobs) and get_job_status (which polls progress).

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 clear context: it should be used after uploading the file via HTTP PUT to the upload_url, and it explicitly recommends polling get_job_status afterward. It doesn't explicitly state when not to use the tool, but the precondition and follow-up are clear enough to guide proper usage.

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?

With no annotations, the description carries the full burden and does so: the exact two-call payment flow, rejection of invalid edits before any charge, the do-not-add-or-change-a-word constraint, up to 300 cuts/60 minute output, first-occurrence matching for repeated phrases, 72h vs 24h TTL differences, retry-with-job_id recovery, and auto-refund on failure. This is an unusually complete behavioral disclosure for a paid, stateful tool.

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 purpose and alternative, then flows into the numbered two-call flow. Every sentence is substantive given the tool's complexity (payment, validation, TTLs), though the density is high and a reader must parse a lot in one pass.

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 annotations and no output schema, the description covers return artifacts (clip-video, clip-srt, clip-words re-timed), error handling, pricing, and lifecycle. Nothing an agent needs to invoke this complex paid flow correctly appears to be 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 0% and there are 5 undocumented parameters with 0 required, so the description must compensate fully. It does: it maps source_job_id + edited_transcript (inline, max 262144 UTF-8 bytes) + optional title to call one, and job_id + payment_credential to call two, and explains the transcript's [NNNN] line format.

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: 'Cut and re-assemble a video from an edited copy of its own word-level transcript.' It explicitly distinguishes itself from sibling clips_from_job ('the text-editing counterpart to clips_from_job's timestamp-based cutting') and from extract_clip, so an agent can place it 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?

Gives an explicit decision rule: 'Use whenever the edit is easier to describe in text than in timestamps... use extract_clip instead when you already know the exact start/end seconds.' It also names prerequisites (parent must have a word-level transcript, source still in storage) and the sibling tools that produce valid parents (find_clips, summarize, transcribe).

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?

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses the payment challenge workflow, presigned PUT with 1h expiry, three-step upload completion, the three output roles (clip-candidates, transcript, transcript-words), source retention for 72h, flat pricing ($2.00) and auto-refund on failure, plus retry semantics with job_id. This is exceptional 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 appropriately so for a multi-step, high-stakes workflow. It is front-loaded with 'START HERE' and the critical anti-pattern warning, then follows a logical sequence (call flow, outputs, pricing, reuse). While dense, every sentence contributes essential information—no filler. The length is justified by the tool's 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?

Given the tool's complexity, lack of annotations, and lack of output schema, the description is remarkably complete. It covers the entire lifecycle: initial call, payment, upload, completion, output schemas (referenced via /.well-known/ endpoints), source-reuse contract, pricing, failure behavior, and retry semantics. An agent has everything needed to correctly invoke and interpret the 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?

While schema coverage is 100% and each parameter has a description, the description adds workflow-specific meaning beyond the schema: it explains that filename is required on the first call, job_id can be used alone to recover state, and payment_credential must accompany job_id to confirm payment. It also clarifies that query switches the analyzer mode. This goes well beyond the schema's basic definitions.

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 states a precise purpose: 'Identify ranked candidate clips in a video — what to cut for highlights, social, or testimonials.' It also clearly positions itself as the canonical entry point ('START HERE for any clip workflow') and explicitly distinguishes itself from transcribe and clips_from_job, so an agent can differentiate it from siblings immediately.

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 is explicit about when to use the tool: 'START HERE' and 'Do not call transcribe first' with a concrete reason (doubles upload and spend). It lays out the exact three-call flow, explains optional query mode, references clips_from_job for subsequent cuts, and even lists applicable use cases (interviews, podcasts, sales calls). No alternatives are left ambiguous.

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?

With no annotations, the description carries the full burden, and it delivers: it discloses state values, the inline-vs-download_url output split, 1-hour URL expiry, expected completion times, derivative-job state exceptions, and the publish_youtube edge case. This is far richer than a generic status check.

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 dense and well front-loaded: the core status/output facts come first, followed by polling, derivative jobs, and recovery. Each paragraph has a distinct purpose with no filler, though it is somewhat wordier than necessary because it echoes format-enum details already present in the schema.

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 tool with no output schema, this description explains the output shape, role-keyed entries, state transitions, timing expectations, and failure recovery paths. An agent has everything it needs to call the tool correctly 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. The description adds real value by explaining that format returns transcript inline in a top-level field, describing derivation relationships (txt/vtt from SRT, json vs words), and noting job_id can recover a lost challenge or upload URL. It still partly repeats the schema's enum details, so it stops short of 5.

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?

Opens with a precise verb+resource: 'Check the status of a transcribe or summarize job', and immediately states what it returns (current state and outputs). It also explicitly covers derivative jobs and lost-state recovery, so an agent can distinguish it from siblings like complete_upload or clips_from_job.

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: poll after complete_upload, wait at least 60 seconds, use it to recover lost state, and understand how derivative jobs differ. It names the triggering workflow and gives concrete timing expectations, leaving no ambiguity about how to apply the tool.

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?

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: statelessness ('no job is created, no database row written'), the $0.01 USDC cost per attempt, the two-call protocol with expected responses, and the relationship to paid product tools. This is comprehensive and exceeds what annotations would typically provide.

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 relatively long but each sentence contributes meaningful information: the flow, cost, statelessness, and use case. While it could be tightened, the structure logically moves from purpose to flow to benefits, making it effective despite its length.

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 description is complete for the tool's complexity: it covers the two-call flow, expected response format, cost, side effects (none), and when to use it. No output schema exists, but the description describes the response structure ('{paid: true, timestamp, receipt_ref, payment_method}') so the agent knows what to expect.

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 schema already has 100% coverage for the single parameter, so the baseline is 3. The description adds value by explaining the credential's role in the two-call flow, providing an example format ('Payment eyJ...'), and explicitly stating to omit it on the first call. This enriches the schema's description without redundancy.

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 this is a smoke test for MPP payment plumbing, with a specific verb ('smoke-test') and resource ('MPP payment plumbing via this MCP server'). It distinguishes itself from sibling paid tools by explicitly noting it uses the same verification path as transcribe/summarize but costs only $0.01 USDC and creates no job.

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 usage guidance is provided: 'Use this whenever you want to confirm a wallet, the MCP transport, the worker, and the production payment middleware are all healthy without paying a transcribe price.' It also explains the two-call flow, making it clear when and how to use it as an alternative to paid tools.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the multi-step stateful flow (job creation, payment, upload, completion), the presigned PUT URL expiry (1h), idempotency on retry with job_id alone, and automatic refund on failed jobs. It also details the output structure (roles 'summary', 'transcript', 'transcript-words') and the format options. This level of transparency is exceptional and leaves no hidden side effects or prerequisites unstated.

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, but every sentence carries essential information: the core output, the warning against transcribe, the three-call flow, the output formats, pricing, and use cases. It is not concise in word count, but it is efficiently organized—front-loading the main purpose, then the procedural details, then pricing and use cases. No filler is present; the length is justified by the tool's complexity. A slightly structured list could improve scannability, but the content earns its length.

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 tool with a multi-step payment flow, multiple output formats, and a dependency on external endpoints (mpp.json, weftly-transcript-v2 schema), the description covers all necessary details: the exact sequence of calls, the payment mechanism, the upload URL expiry, the output roles, the format derivations, and the fallback for retries. There is no output schema, so the description must explain the return values, which it does comprehensively. An agent could successfully invoke this tool from the description alone.

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 input schema already documents each parameter (job_id, filename, payment_credential) with descriptions and formats (100% coverage). The description adds meaningful context beyond the schema by explaining the call flow—when each parameter is required (filename on first call, job_id+payment_credential on second) and the purpose of each step. It also enriches the filename parameter by listing supported extensions and clarifying that it infers media type. While the schema covers the syntax, the description adds the semantics of sequencing, which is valuable.

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 states a specific verb ('Summarize'), a specific resource ('an audio or video file'), and the dual output (text summary plus full transcript with per-word timestamps). It explicitly distinguishes itself from the sibling tool 'transcribe' by instructing 'Do not also call transcribe on the same file,' which clearly separates the two tools. The description also enumerates the output roles and formats, leaving no ambiguity about what the tool produces.

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 gives explicit usage context: 'Use for meetings, long-form interviews, lectures, and podcast episodes' and notes when the 'words' output is beneficial (creating clips, multicamera edits). It also provides a clear when-not instruction ('Do not also call transcribe') and explains the full three-call flow, including the need for payment and upload, which is essential for correct invocation. This is far beyond a vague suggestion—it tells the agent exactly when and how to use the tool.

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?

With no annotations provided, the description carries full behavioral disclosure. It discloses the multi-step payment flow, presigned URL expiry (1h), idempotency ('Retrying any call with job_id alone returns current state'), auto-refund on failure, and details the exact output roles and formats. This is exceptionally transparent for a complex tool.

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 every sentence earns its place. It is front-loaded with the core purpose, then the flow, then formats, pricing, and edge cases. It avoids fluff and uses structured lists (numbered steps, pipe-separated formats). Slightly longer than minimal but appropriately dense for the tool's 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?

Given the three-call flow, no output schema, and multiple formats, the description covers everything an agent needs: the exact call sequence, parameter usage, output formats via get_job_status, pricing table reference, idempotency, and refunds. Nothing critical is missing for correct 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% and each parameter already has a description, but the tool description adds meaningful context beyond the schema: filename infers media type, payment_credential is the full Authorization header value, and job_id alone recovers state if the response was lost. It explains how each parameter fits into the three-call flow, substantially enriching semantics.

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-resource pair ('Transcribe audio or video to text') and immediately distinguishes itself by noting per-word timestamps for precise editing. It also names the three-call flow and output formats, clearly differentiating it from sibling tools like get_job_status or edit_from_transcript without requiring schema inspection.

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 lists use cases: 'podcasts, interviews, meetings, lectures, and especially for creating clips, multicamera edits, or edit-video-from-transcript where word boundaries matter.' It also prescribes the sequential calls to other tools (complete_upload, get_job_status). However, it does not explicitly state when NOT to use it or name an alternative tool for other cases, so it stops short of a 5.

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