hyperframes_still

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

With no annotations, the description carries the full behavioral burden and doesn't meet it: it doesn't say an image file is written to disk, whether existing files are replaced, or that overwrite must be set explicitly (that fact lives only in the schema). It does add the useful note that output_path is auto-generated when omitted.

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 one-sentence purpose followed by an Args list where each line adds real semantics (path type, default, inline-vs-file). No redundant prose, though the Args block is a bare docstring dump rather than tailored guidance.

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 needn't be described. But for a file-writing render tool with zero annotations, the description omits the sibling disambiguation and the overwrite/protection behavior that an agent needs to call it safely.

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 only 17%, so the description must compensate and largely does: it explains project_path as an absolute project directory, output_path fallback behavior, frame numbering with default 0, and crucially the distinction between inline `variables` and `variables_file`. The one uncovered parameter, overwrite, is documented in the schema itself.

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 and resource: 'Render a single frame as image from a Hyperframes composition.' That is clear and concrete, but it never distinguishes the tool from close siblings like hyperframes_snapshot, hyperframes_capture, or hyperframes_preview, which an agent must otherwise infer.

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?

No guidance on when to use this versus hyperframes_snapshot/capture/preview/render, nor any prerequisites (e.g., project must be initialized or validated). The reader is left to guess from the name alone.

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