results_animate

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 reveals that an optional extra is required, frames are ordered by numbers, one shared color/crop/camera is applied, small GIFs are returned inline, and the file path always returned. This goes beyond schema details and gives useful operational context, though it doesn't mention side effects like file creation explicitly.

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 three sentences, front-loaded with the main action, then clarifies the key input and output behavior. Every sentence earns its place, with no redundant filler or repetition of schema details.

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 12 parameters, no output schema, and no annotations, the description covers the essential points: purpose, prerequisite, input semantics, shared configuration, and output format. It leverages the sibling results_render to avoid repeating option semantics. It doesn't explain every parameter but provides enough for an agent to select and invoke the tool correctly, especially with descriptive parameter names.

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. It explains 'files' in detail (directory or glob, numeric ordering) and references 'Coloring/warping/crop_bounds options as in results_render,' which helps for those parameters. However, many parameters like fps, max_frames, show_edges, warp_factor, window_size, and gif_path are not individually described. The names and defaults are somewhat self-explanatory but the description does not add substantial meaning beyond the schema for them.

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+output: 'Render a time series of VTK/VTU results into an animated GIF.' It clearly distinguishes from sibling results_render (static rendering) by focusing on time series animation, making its purpose 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?

It states the prerequisite (requires pyvista 'viz' extra) and explains what 'files' should be (directory or glob with numeric ordering). The reference to 'as in results_render' implies shared options, and the existence of results_render as a sibling provides clear context for when animation is intended versus a single-frame render. It doesn't explicitly say 'use this instead of results_render for animations,' but the distinction is strongly implied.

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