gif_patch

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, and it delivers thoroughly. It explicitly states that 'palette' swaps colors in every color table including per-frame local tables, makes zero generation loss, and doesn't touch frame data. It discloses the quantization behavior for 'retime' (10ms steps, 20ms minimum) and the exact pixel preservation limits (255 opaque colors, nearest-palette snapping beyond that). It even explains the failure mode where 0 matches means the hex isn't in the file. This is exemplary transparency for a tool with no annotations.

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 information-dense and front-loaded with the most critical distinction (operations on animated GIFs) in the first sentence, then dives into action-specific details. The structure uses a clear 'palette' / 'retime' split, making it scannable for an agent. It's long, but every sentence earns its place — the real-bug example adds significant context for decision-making. The only minor deduction is that the final example of the 1.8s-vs-0.62s bug is somewhat verbose and could be tightened without losing its instructional value.

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 5 parameters, no annotations, and no output schema, the description is remarkably complete. It covers what each action does, the limitations (quantization, palette depth), the failure mode of the response (0 matches), and provides a decision rule for when to use the sibling tool. An agent has everything it needs to select between palette and retime, construct the parameters correctly, and interpret the result. The only theoretical gap is the absence of the full return format, but the description's statement that 'the response reports how many table entries each source colour actually matched' is sufficient for an agent to validate the outcome.

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 coverage is only 40% (2 of 5 parameters have descriptions), so the description must compensate — and it does. It explains that 'colorMap' is a mapping of source hex to target hex for the palette action, and that 'msPerFrame' is the delay per frame with quantization behavior. It also clarifies the conditional nature of parameters (colorMap for palette, msPerFrame for retime) and that 'action' is the discriminator. The connection between 'file' and 'outFile' is implied but the description doesn't explicitly say that outFile is the write destination — a small gap that keeps this 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?

The description clearly identifies the tool as operating on animated GIFs with two distinct actions ('palette' and 'retime'). It specifies the exact resource ('animated GIFs'), the verbs ('swaps colours', 're-times all frames'), and critically states what it does NOT do ('without touching frame data'), which differentiates it from sibling tools like sprite_repaint. The description uses specific terminology ('global AND per-frame local', 'zero generation loss') that gives the agent a precise mental model of the tool's scope.

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 provides explicit guidance on when to use each action: 'palette' for re-dressing indexed sprites, 'retime' for fixing animation timing issues. It names the sibling tool 'colors_inspect' as the alternative for finding exact hexes when a color returns 0 matches. It even includes a concrete real-world scenario ('a real bug this fixes') that helps the agent recognize when retime is the right choice vs. dropping frames. This is well above the minimum viable guidance.

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