Batch-render many .riv files/formats in one call

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

With no annotations provided, the description carries the full behavioral burden and discharges it thoroughly. It discloses the concurrency model ('sequentially reusing the same headless Chromium page (no parallel pages)'), the absence of watch mode and why, the merge semantics ('each job's own fields override them'), and error isolation ('One job's failure does not stop the batch') including the per-job report fields. This far exceeds typical 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?

The definition is a single front-loaded paragraph where the opening sentence states the core function and each subsequent sentence adds a distinct operational fact (use case, defaults semantics, error handling/report). Every sentence earns its place, and the length is justified by the absence of annotations. The final sentence is slightly dense, but the structure is strong.

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 a complex nested jobs array (up to 200 items), no annotations, and no output schema, the description covers a great deal: input structure, execution model, CI/script use case, defaults merging, failure semantics, and the per-job report fields (success/error/outPath/durationMs). It stops slightly short of specifying the exact top-level return shape (e.g., how the entries are aggregated), but for a tool of this complexity it is remarkably 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 description coverage is 100%, so the baseline is 3 and the schema already documents every parameter, including the defaults merge rule ('Shared defaults merged under each job (job-level values win)') and the rivPath/glob mutual exclusivity. The description's contributions — framing a job as either a rivPath or a glob and restating the override rule — add only marginal comprehension value beyond what the schema already states.

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 and resource: 'Render a list of jobs — each a single .riv (rivPath) or a glob of .riv files (glob) — to png/gif/apng/webm/sprites'. It names the exact output formats and the two input modes, and the batch/sequential framing differentiates it from the single-render siblings (riv_render_gif, riv_render_frame, etc.). An agent can tell at a glance what this tool does and how it differs from the per-format render 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 gives clear context: 'Built for CI/scripts: call this tool repeatedly from your pipeline instead of expecting a live watch mode — none is provided, since MCP's request/response model doesn't fit a background file watcher.' This tells the agent the intended invocation pattern and sets an explicit exclusion (no watch mode). It does not, however, explicitly route to a sibling alternative for single-file renders.

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