convert

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

No annotations are supplied, so the description carries the full burden; it does disclose key defaults: output lands next to the input, overwrite refuses by default, dry_run returns the ffmpeg command rather than executing, and timeout_s kills ffmpeg. It omits failure behavior, whether partial outputs are cleaned up, and any permission or resource constraints for a long-running ffmpeg invocation.

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 purpose sentence followed by a compact format inventory and a param-by-param block; no filler. The format enumeration is dense but scannable and each clause carries distinct 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?

An output schema exists, so return values need no prose; the description instead spends its budget on defaults and failure-adjacent knobs (overwrite, timeout_s, dry_run), which is the right allocation for a mutating media tool with no annotations. Only error/cleanup behavior remains uncovered.

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%, so the description must compensate, and it largely does: format vs. output extension precedence, quality's low/medium/high trade-off, overwrite default-refuse, dry_run return semantics, and timeout_s behavior. Only `input` (accepted path/URL forms) is left unelaborated, which keeps it from a 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?

States a clear verb+resource ("Convert a file to another format") and enumerates supported target families (mp4/mov/mkv, webm, mp3/wav/flac, gif). It actively distinguishes itself from two siblings by name — make_gif for gif control and compress for size limits — so an agent can route without opening schemas.

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 alternative routing for two cases: gif trimming (use make_gif) and size-limited output (use compress). No guidance on when to prefer extract_audio, transform, or concat over converting, so it stops short of full when/when-not coverage.

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