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

With no annotations, the description carries the behavioral burden. It discloses the path-resolution quirk ('the server's working directory is the client's, not your project's') and explains that unmatched pixels indicate gaps in region definitions. It does not explicitly state read-only, but 'Show' and 'census' imply non-destructive inspection, and no contradictions exist.

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 moderately long but every sentence adds context: the main action, the optional census, the required parameter condition, and a path caveat. It is front-loaded with the core purpose and avoids redundancy.

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 an inspection tool with no output schema, it fully describes what is returned (canon details and census counts) and explains how to interpret results (unmatched pixels). It covers the key operational caveat about paths and leaves no obvious gap for an agent to call it correctly.

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 100%, so the baseline is 3. The description adds real value by explaining that canonPath and censusFile serve as the search origin and that censusFile also counts frame membership, plus the semantic meaning of unmatched pixels. This goes beyond the individual parameter descriptions.

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 uses a clear verb ('Show') with a specific resource (the resolved canon), and enumerates exactly what is shown (palette size, regions, rules, protection flags, scale table, thresholds) plus the optional census operation. This distinguishes it from sibling tools like canon_init or canon_learn by describing a distinct inspection/analysis action.

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 provides a strong usage condition ('Pass canonPath or censusFile — without either there is nowhere to search from') and warns about the server working directory. However, it does not explicitly compare against sibling tools or state when to prefer this over others, so it clarifies how to call but not when to choose it.

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

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

With no annotations provided, the description carries the full transparency burden. It discloses the file-creation behavior and the palette-learning algorithm: colors must occur at least minCount times, rarer colors are usually anti-aliasing noise. It could go further by stating what happens if the file already exists, but the described behavior is substantive and not hidden.

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 only three sentences, front-loads the main purpose, and each sentence contributes meaningful information. There is no filler or repetition of the input schema.

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 7 parameters and no output schema, the description provides the essential context: what file is created, what data it encodes, how the palette is learned, and when to run the tool. It omits edge-case guidance such as behavior with an existing sprite-canon.json, but the schema compensates for parameter-level detail.

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?

The schema description coverage is 100%, so the baseline is 3. The description adds useful context around the palette-learning threshold meaning of minCount, but it does not map parameters or clarify options like updatePalette beyond what the schema already provides.

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 and resource: 'Create sprite-canon.json for a project', and explains that the file is the single source of truth for palette, regions, scale, and thresholds. It is clear and not tautological, though it never explicitly contrasts itself with sibling tools like canon_learn.

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 gives strong lifecycle guidance: 'Run once per project, then commit the file', which tells the agent initialization is a one-time action per project. It does not explicitly state when not to use this tool or when to prefer a sibling like canon_learn for updating an existing canon.

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

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

With no annotations provided, the description carries the full burden, and it does so thoroughly. It explains the fixed luminance-range behavior for repaint, that protected regions are never repainted and cause verify to fail if touched, that updates merge additively, and that replace=true is required to remove mis-sampled colors. These are exactly the nontrivial behavioral facts an agent must know before calling the tool.

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 a single dense paragraph, but every sentence carries meaningful content: region definition, sampling, luminance range, protected regex, HSL rules, and replace/merge semantics. It is slightly unstructured, but the length is justified by the complexity of the tool's behaviors.

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 this tool's complexity (13 parameters; no annotations; no output schema to lean on), the description covers all the essential behavior safely and completely: how to define a region from colors, HSL, or points; how protection works; fixed luminance behavior; how update/merge works; and how to remove colors. Very little is left to an agent's guess.

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 92%, so the baseline is 3, but the description adds significant meaning beyond the schema: it explains how sampled colors expand via `absorb`, how HSL rules need `lumRange` for repainting, what `protected` means, and how `replace=true` differs from the default merge. This goes beyond the bare property descriptions to explain how parameters relates to one another.

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 clear verb+resource: 'Define or update a named region in the canon,' and gives concrete examples (skin, hair, outfit, outline). It is easily distinguished from sibling tools like sprite_repaint or sprite_verify, since it is about defining regions rather than painting or verifying them.

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 for when to use the tool—defining or updating canon regions—and explains which sampling modes to use when (points, explicit colors, HSL rules). It does not explicitly name alternatives or state 'use X instead,' but the workflow interactions with repaint and verify are described, so an agent gets a solid sense of when this tool is relevant.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool lists colors sorted by frequency with luminance, and mentions it handles spritesheet cell dimensions (cellH/cellW) for PNG sheets. However, it doesn't disclose potential performance implications for large files, whether it reads from disk or memory, or any side effects (though it's clearly a read-only inspection tool). The description adds some behavioral context beyond the schema (e.g., the purpose of cellH/cellW), but lacks details on output format or edge cases.

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 two sentences, front-loaded with the core function (list colors by frequency with luminance) and immediately followed by the use case. Every sentence earns its place: the first states what it does, the second explains why it matters and what to look for. No fluff or repetition.

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 the tool's complexity (4 params, no output schema, no annotations), the description is fairly complete. It explains the purpose, the use case, and hints at the spritesheet handling. However, it doesn't specify the output format (e.g., list of hex codes with counts), which could be important for an agent to parse results. Since there's no output schema, the description could have mentioned the return structure. Also, it doesn't clarify whether 'files' accepts glob patterns or specific paths, which might be relevant. Overall, it's good but not exhaustive.

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 75% (3 of 4 parameters have descriptions). The description adds meaning by explaining the purpose of the tool's output (raw material for canon decisions) and how cellH/cellW relate to spritesheet handling. It doesn't explicitly describe the 'files' parameter beyond the schema, but the schema already covers it. The description compensates for the missing 'top' parameter description by implying it controls the number of colors listed (default 40), which is not in the schema. This adds value beyond the schema.

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 states the tool lists colors used in files, sorted by frequency with luminance, and explicitly frames it as raw material for canon_init/canon_learn decisions. This distinguishes it from sibling tools like sprite_measure or sprite_verify, which focus on dimensions or verification rather than color analysis.

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 clear context for when to use this tool: to spot near-duplicate colors, anti-aliasing noise, and map hexes to visual parts before defining regions. It implies this is a preliminary analysis step before canon_init/canon_learn, but doesn't explicitly state when NOT to use it or name alternative tools for other color-related tasks. The sibling list includes canon_init and canon_learn, which are the downstream consumers, but no explicit exclusion is given.

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

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.

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

No annotations are provided, so the description carries the behavioral burden. It does add useful context: measurements are per-frame, canon regions affect which rows are returned, and row positions can vary across frames. However, it does not explicitly state whether the tool mutates anything, how it handles missing canon files, or what the return format is. 'Measure' implies read-only behavior, but the description leaves some behavioral details implicit.

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 a bit longer than the minimum, but each sentence earns its place: the first lists what is measured, the second gives the intended timing, and the third grounds the guidance in a concrete failure mode. It is front-loaded and readable, though the bug anecdote could be trimmed without losing core meaning.

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 measurement tool with no output schema and no annotations, the description covers the key outputs, the per-frame nature, and the role of canon regions. The input schema handles the parameter semantics. It stops short of describing the exact return structure or edge-case behavior, but it gives an agent enough to invoke the tool correctly and interpret its results.

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 schema already documents all four parameters. The description adds conceptual context around canon regions, which relates to canonPath, but it does not give additional parameter-level detail beyond the schema. Per the rubric, baseline 3 is appropriate here.

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 and resource: 'Measure a sprite's anatomy per frame and its cross-frame jitter.' It enumerates concrete outputs (bounding box, top row, widest row, cap width, waist row, region first rows), which makes the tool's purpose unmistakable. This clearly distinguishes it from siblings like sprite_verify or sprite_repaint, which do not measure anatomy.

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 an explicit use case: 'Use before placing anything relative to a sprite: measured rows beat guessed proportions.' It also provides a concrete bug example showing when this tool prevents errors. It does not name alternative tools or state when not to use it, but the context is strong enough for an agent to route correctly.

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

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

With no annotations, the description carries full weight. It discloses determinism, luminance mapping via fixed recorded range, silhouette invariance, protection of regions, and write behavior (never overwrites input unless identical outFile). These are behavioral promises beyond what the schema reveals, giving the agent a reliable mental model.

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 slightly long but every sentence contributes: purpose, guarantees, variant guidance, output behavior. It front-loads the core purpose and packs the rest efficiently. No filler, though the length might be trimmed without losing 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?

For a 9-parameter tool with no output schema, the description covers the essential behavior: determinism, shading preservation, masks, and file output. It does not explain what the resulting file contains (e.g., format, dimensions) but those are likely inferred from input. The clerical params (rows, cell dimensions, canonPath) are not discussed, but they are not core to understanding the tool's function. Overall, an agent can call it correctly based on this text.

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 78%, so baseline is 3. The description adds meaning for ramp (dark→light hex list), maskFromFile (explains variant matching and paint application), and outFile (overwrite rule). It does not elaborate on rows, cellH/W, or canonPath, but those have schema hints and are auxiliary. Overall it enriches several key parameters beyond schema text.

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 precise verb–resource pair (“Deterministically recolour a canon region”) and immediately contrasts it with AI regeneration, clearly marking scope and intent. The explicit mention of maskFromFile and outFile behavior also disambiguates it from sibling tools like sprite_verify or sprite_measure.

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 primary use case (deterministic recolor vs. AI) and gives an explicit directive for a specific parameter: “Use maskFromFile when repainting an already-recoloured variant.” It also explains the region-matching logic and when outFile may overwrite the input. This is concrete, actionable guidance beyond generic 'when to use'.

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

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

With no annotations, the description carries the burden. It explains the output (returns an image) and mentions the behavior of returning path only for large sheets in the schema. It doesn't mention potential side effects like file overwriting or error conditions, but the core behavior is adequately described.

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 slightly verbose with a motivational clause ('every visual defect we ever caught...'), but it's still concise and well-structured. It opens with the verb and object, then details, and ends with a usage tip. The extra sentence adds value without being redundant.

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 the 8 parameters and no output schema, the description provides sufficient context for typical use: it's for visual inspection and consistency checking. It doesn't elaborate on error scenarios or edge cases, but the core purpose and usage are covered. The context signals (sibling tools) further clarify its role.

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?

All parameters are described in the schema with clear meanings (e.g., files, outFile, crop, zoom, cellW, cellH, maxFrames, returnImage). The description reinforces key concepts like row-per-file and column-per-frame. The schema coverage is 100%, and the descriptions are precise, leaving little ambiguity.

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 states the tool's function: composing a zoomed contact sheet from sprites. It specifies the arrangement (one row per file, one column per frame) and that it returns an image, making its purpose unambiguous and distinct from sibling tools like sprite_measure or sprite_verify.

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 usage context: it's for visual inspection and consistency checking ('so you can LOOK at what you just made', 'Judge consistency on sheets'). It also hints at using crop for zooming. However, it doesn't explicitly contrast with alternative tools or state when not to use it, though the context is fairly clear.

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

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

With no annotations provided, the description carries the full burden, and it does substantial work: it discloses that the tool returns pass/fail numbers, explains what each check verifies, and notes that directories are accepted (all PNG/GIF inside). It does not explicitly state that it is non-destructive or describe error behavior, but 'verify' plus the pass/fail framing makes the core behavior clear.

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 dense but every sentence earns its place: the purpose is front-loaded, the check list is compactly structured, and the directory-handling note is directly actionable. No filler or repetition of schema content.

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 the tool's complexity — 8 parameters, 6 checks, no output schema, and no annotations — the description covers the essential behavioral surface: what checks exist, what they catch, and how file inputs behave. It falls slightly short on specifying the exact return structure beyond 'pass/fail numbers' and on edge-case behavior, but it is strong enough for an agent to select and invoke the tool correctly in most cases.

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. The description adds meaningful semantics beyond the schema by explaining the check enum values in detail (e.g., 'spread' catches 'bright from behind, dark from the front') and by clarifying that 'files' may be directories containing PNG/GIF. This elevates it above the baseline.

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 and resource: 'Run numeric consistency checks and get hard pass/fail numbers.' It then enumerates the exact checks (palette, jitter, spread, protected, leftover, scale) with one-line semantics, making the tool's scope unmistakable and clearly distinct from siblings like sprite_measure or sprite_repaint.

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 implies when to use the tool — 'the replacement for eyeballing hundreds of frames' — and clarifies that it is for numeric consistency verification. However, it does not explicitly contrast with sibling tools or state when NOT to use it, leaving the agent to infer the boundary against sprite_measure or colors_inspect.

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