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.