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

With no annotations, the description carries full burden. It discloses labels burned by default, shorter file holds final frame, panel height derived from A and forced onto B, stateMachine precedence over animation, and default background behavior. These are meaningful behavioral traits beyond parameter names.

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 well-organized paragraph that front-loads the core purpose, includes concrete examples, and differentiates from alternatives without redundancy. Every sentence contributes 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 tool with 14 parameters and no output schema, the description covers key behaviors, defaults, and the output format. It could mention what the tool returns (e.g., path to output file), but overall it provides sufficient context for an agent to decide and invoke 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 applies. The description reinforces that artboard/animation/stateMachine are applied to both files, but this is already present in the parameter descriptions. No new semantic value is added beyond what the schema 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 clearly states the tool renders two .riv files side by side into a composite GIF/APNG, with specific verbs and resource types. It also explicitly differentiates from riv_visual_diff, making the purpose unmistakable even among sibling 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 provides explicit when-to-use guidance (e.g., 'rig before/after an edit', 'design variants') and names the alternative riv_visual_diff, explaining why this tool is chosen for side-by-side review rather than pixel diff.

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 burden. It discloses network access, the two operational modes, and that import mode has the same output as riv_import_svg. This covers key side effects and dependencies, though it omits details about error cases or rate limits.

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 purpose, then concisely explains modes and network needs. Every sentence contributes meaningful information without 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?

With no output schema and 5 parameters, the description clearly explains the two main usage modes and result behavior. However, it leaves gaps around parameter combinations (e.g., both query and icon provided), idPrefix semantics, and error conditions, making it adequate but incomplete.

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 80%, but the description adds meaning by explaining the relationship between icon and outSpec, and the query-only mode. However, idPrefix remains undocumented, and required-combination behavior is only implicit.

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 it searches Iconify's ~200k icons and converts one into Rive shapes, with specific mention of two modes. It distinguishes itself from siblings by referencing riv_import_svg's output equivalence.

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 explains two modes, network requirements, and references an alternative tool (riv_import_svg) for output. However, it doesn't explicitly state when NOT to use this tool or when to prefer riv_import_svg directly.

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 fully carries the behavioral transparency burden, and it exceeds expectations. It discloses sequential reuse of a single Chromium page, explains that failures are isolated, and specifies the per-job report fields (success/error/outPath/durationMs). It also preempts the expectation of a watch mode.

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 dense but well-organized paragraph that front-loads the core purpose, then adds necessary operational details. Every sentence contributes distinct information: execution model, target use case, defaults semantics, and error handling. No filler or redundancy with the 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?

This is a complex tool with nested objects and multiple output formats, and the description covers the key contextual gaps not present in the schema: the sequential page reuse, lack of watch mode, fault isolation, and the shape of the returned report. Given the rich schema and no output schema, this is a complete operational picture.

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%, and the schema already documents parameter constraints and defaults. The description adds meaningful semantic value by explaining how the 'defaults' object merges with each job and how job-level fields override shared options. It also clarifies the behavior of the jobs array in terms of ordering and isolated failures.

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 action ('Render a list of jobs') and names the exact resources/formats (.riv files, png/gif/apng/webm/sprites), distinguishing this batch tool from single-render siblings like riv_render_gif and riv_render_video. It clearly defines the two job input modes (rivPath and glob).

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 strong contextual guidance: it is built for CI/scripts, should be called repeatedly from a pipeline, and no watch mode is available because MCP is request/response. It also explains defaults merging and job-level overrides. However, it does not explicitly name alternative single-render tools or state when to prefer batch over single rendering.

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 that the tool validates with the official runtime, embeds PNG/WAV/MP3 assets, returns a preview frame, and explicitly notes that the server's own preview does not play audio even though audio events are written correctly. It does not mention overwrite behavior or failure handling, but the main side effects are well covered.

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 long but well-structured, with front-loaded purpose, example JSON blocks, and labeled sections for presets, pro features, imports, and audio. Each section earns its place given the tool's complexity, though the sheer length prevents a 5 on conciseness.

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 complexity, lack of annotations, and absence of an output schema, the description is remarkably complete. It covers scene specification, character rigging, motion presets, advanced features, import flow, z-order, animatable properties, colors, easing, and audio behavior—including a note about runtime playback limitations. An agent has enough detail to use the tool 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?

Although schema coverage is 100%, the schema descriptions are minimal (e.g., "Scene spec (see tool description for schema)"). The description fills this gap with extensive examples of scene structure, keyframe syntax, presets, pro features, imports, and audio configuration, far exceeding the baseline. It gives every parameter meaningful context.

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 a working .riv animation file from scratch" and adds validation plus a rendered preview frame. This clearly differentiates riv_create from siblings like riv_edit, riv_import_svg, and riv_render_frame.

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 a recommended flow: riv_design_tokens → (riv_import_svg / riv_asset_search) → riv_create → riv_critique, establishing when to use it. It also states preferences: "PREFER imported real vector art over drawing with primitives" and "PREFER these over hand-authored keyframes." However, it does not explicitly say when NOT to use this tool (e.g., for editing existing files, use riv_edit), so it misses explicit exclusions.

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 supplied, the description carries the full burden. It thoroughly discloses what the tool returns (including the nature of the images, that motion vectors are 'computed from the file data', and the fixed 7-axis checklist). It does not mention failure modes or explicit read-only status, but its output-focused transparency is strong. No contradiction with 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 single-paragraph but well-structured with numbered return items (1)-(5) and a clear imperative workflow sentence. Every sentence contributes: purpose, outputs, and usage instructions. No fluff, scannable despite length.

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 complexity (7 parameters, no output schema, no annotations), the description is remarkably complete. It explains what the tool produces, how to interpret the visual outputs, what the checklist covers, and how to loop the critique into revision. It even sets an iteration minimum. This is sufficient for an agent to select and execute the tool 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 71%, so the baseline is 3. The description adds meaning to the 'frames' parameter by linking it to 'N frames left→right across the duration' and implies the token-saving intent of 'width' indirectly via 'keep small', but does not explain 'artboard', 'stateMachine', or 'individualFrames' beyond the schema. Overall, moderate additional value.

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 a specific verb+resource: 'Critique a .riv' via a 'One-call review bundle'. It enumerates the five distinct return types (filmstrip, onion-skin, motion report, metrics+lint, checklist), distinguishing it from sibling render or inspect 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?

Explicitly places the tool in the 'render→critique→revise loop' and gives actionable workflow instructions: 'LOOK at the images, score each axis 1-5, fix anything below 4 (riv_edit / regenerate), then re-run. Iterate at least twice...' It also names alternatives (riv_edit/regenerate), making usage context and next steps unambiguous.

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 not disappoint. It discloses the parentId resolution behavior for editor-authored files, explains that unsupported object types are counted in 'skipped' rather than silently dropped, and flags licensing attribution for community/marketplace files. This goes beyond basic operation, though it omits side effects like writing the outSpec file and the default return behavior (which only appear in the schema).

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 meaty paragraph, but every sentence carries substantive information: the core operation, supported features, parentId handling, skipped counting, workflow use, sample pointer, and licensing note. It is dense yet front-loaded with the primary purpose, and while it could be trimmed, it is not inflated with filler.

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 complex conversion tool with no output schema, the description covers a wide range of relevant behavior: the exact types of content preserved, file provenance handling, unsupported-content visibility, practical use cases, and legal considerations. It does not fully specify the return format (only 'scene spec' and the schema's 'return summary only'), but it is broadly adequate for an agent to understand scope, limitations, and expected outcomes.

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 already provides 100% coverage for both parameters (path and outSpec), so the baseline is 3. The description adds workflow context (decompile → edit spec → riv_create) and mentions the scene-spec output, but does not elaborate on parameter syntax or formatting beyond what the schema names. It is adequate but does not significantly enhance schema understanding.

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 ('Reverse') and identifies the exact resource and output ('a .riv file into a riv_create scene spec'). It further enumerates the included element types (shapes, bezier vertices, fills, blend modes, etc.), clearly distinguishing this tool from siblings like riv_dump or riv_inspect by its transformation goal and editable-spec target.

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 explicitly tells when to use this tool: 'study professional files as few-shot examples, or to remix them', and provides a concrete workflow (decompile → edit spec → riv_create with sample reference). It lacks explicit 'when not to use' or named alternatives, but the use cases are clearly framed with enough context to guide selection.

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 full burden. It discloses deterministic generation, OKLCH harmonization, WCAG contrast ratios, and Material-Motion-derived durations, which gives insight into behavior beyond simple generation. It does not explicitly state side-effect-free behavior, but 'generate' implies no mutation, and the lack of side-effect warnings is acceptable.

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 that are information-dense yet concise. It front-loads the core purpose and immediately follows with usage constraints, with no 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?

The tool has no output schema, but the description enumerates the token categories returned, effectively compensating for missing return documentation. It also covers input options and the ordering requirement relative to riv_create. Minor gap: no mention of how results are returned (e.g., JSON structure), but the listing of token types provides sufficient context for a generation tool.

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 67% and the description adds meaning by listing the allowed mood values, scheme options, and optional seed color. It contextualizes how these parameters affect generation (mood as hue default, seed as optional brand color), going beyond the raw enum/pattern definitions.

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 generates design tokens deterministically for a scene, listing specific token categories (palette, gradients, motion, spacing, type scale). It also explicitly positions this as a prerequisite step before riv_create, distinguishing it from sibling 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 explicitly instructs to call this first and to use only the returned values in the scene spec, never inventing raw hex colors or ad-hoc durations. This provides clear when-to-use guidance and an explicit alternative/ordering relative to riv_create.

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. It explains the type of output (type counts and property differences) but omits any indication of whether the tool is read-only, how results are formatted, or the effect of the maxDiffs parameter. This is a notable gap for a tool with no annotation safety hints.

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, front-loaded sentence that immediately captures the tool's purpose. It is concise and contains no filler, with every word contributing to understanding.

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?

Despite being a simple diff tool, the description covers the core purpose but leaves out return format and parameter details. Given the presence of a maxDiffs parameter and no output schema, a bit more detail on invocation would improve completeness, but the basic intent is clear.

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 input schema only includes a description for maxDiffs, leaving pathA and pathB as bare string fields. The tool description does not compensate by explaining these parameters or the optional maxDiffs, so the parameter semantics are largely undocumented.

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 this tool performs a structural diff between two .riv files, specifying that it reports type count changes and per-object property differences. This specific verb+resource combination distinguishes it from sibling tools like riv_visual_diff, which would handle visual comparisons.

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 usage for structural comparison of .riv files but does not explicitly state when to use it over alternatives such as riv_visual_diff or riv_ab_compare. There is no explicit 'when not to use' guidance, so the usage context is clear but not fully elaborated.

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?

The description discloses a critical non-obvious behavior: large files return a summary unless full=true. Since no annotations are provided, this is important context. It could additionally mention output format or errors, but for a read-only dump tool the disclosure is adequate.

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?

Two sentences, front-loaded with the purpose and key behavior. Every sentence earns its place, with no filler or 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?

Given the simple parameter set and full schema coverage, the description provides the essential context: purpose, use case, and truncation behavior. It lacks explicit return format details, but as a low-level debugging tool this is a minor gap.

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?

Both parameters are fully documented in the schema (100% coverage), and the description only restates the 'full' parameter's behavior without adding new details. Baseline 3 is appropriate when the schema already handles parameter semantics.

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 a specific action ('Dump') on a specific resource ('.riv file's object stream') and enumerates the content (typeKeys, property values, hierarchy). It distinguishes itself from sibling tools like riv_inspect or riv_list by emphasizing its low-level binary focus.

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 phrase 'Useful for debugging and format research' provides clear context for when to use the tool. It does not explicitly mention alternatives or when not to use it, but the stated use cases effectively guide selection.

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 full burden. It discloses several behaviors: lossless roundtrip, automatic subtree + reference remapping for deletes, preview rendering, and detailed setKeyframes modes. However, it does not mention that outPath defaults to overwriting the source file, nor does it clarify what 'preview' means or what the tool returns.

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 compact yet information-dense, with a clear two-paragraph structure. The first paragraph summarizes the main operations and cross-references riv_dump; the second dives into setKeyframes specifics without redundancy. Every sentence adds 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?

The tool is complex with multiple op modes, and the description covers most operational details: op semantics, setKeyframes modes, keyframe format, and using riv_dump for targeting. However, it omits the outPath default behavior and does not describe the return value or preview format, which is notable given no output schema.

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 already covers many parameter descriptions, and the description adds significant meaning: rotation is in degrees, setKeyframes mode semantics (replace/add/remove) with default behavior, and that remove ignores value/easing. It also clarifies how index/name/type are used for targeting, going beyond raw schema listings.

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's purpose: modifying an existing .riv file with four specific operations (set properties, setText, delete, setKeyframes). It contrasts with siblings like riv_create and riv_dump by emphasizing it edits existing files and references riv_dump for finding object indices/names.

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 explicitly tells users to use riv_dump to locate object indices/names, which is a practical prerequisite. It implies this tool is for editing existing files rather than creating or inspecting, but does not list explicit exclusion criteria versus other edit-related siblings.

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 transparency burden. It discloses important behavioral details: file extension inference from magic bytes (PNG/JPEG/WEBP/TTF/OTF/WOFF/WOFF2/GIF) and the skipping of externally-referenced assets. This goes beyond a simple action statement, though it omits overwrite behavior.

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, information-dense sentence that is front-loaded with the primary action and resource. Every clause adds value: asset types, destination, magic-byte inference, and the exclusion of external references. No filler or 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 a two-parameter extraction tool with no output schema and no annotations, the description covers all essential aspects: what is extracted, how files are named, and what is skipped. It could mention folder creation or overwrite behavior, but that is not critical for tool selection or invocation.

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%, with both 'path' and 'outDir' well-described. The tool description adds no additional parameter meaning beyond what is already in the schema, so the baseline score of 3 applies.

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 extracts embedded image/font/audio asset binaries from a .riv file to disk. It specifies exact asset types (ImageAsset/FontAsset/AudioAsset + FileAssetContents pairs) and the magic-byte inference, which distinguishes it from sibling tools like riv_asset_search or riv_inspect.

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 clearly implies when to use the tool (extracting raw embedded asset binaries to disk) and gives context that externally-referenced assets are skipped. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.

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 full burden. It does add useful behavioral context: 'using its real artboard, state machine and input names' implies the tool reads the file and adapts to its contents. However, it omits side effects (e.g., does it write files or return code?) and possible limitations.

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, well-structured sentence that packs significant information (frameworks, source, behavior) without fluff. It is front-loaded with the verb 'Generate' and each phrase adds 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 simple 2-param tool, the description covers the core purpose, but it lacks details about the output format (returned code vs. file generation) and any prerequisites or error conditions. Since there is no output schema, the description should have clarified the return value to be fully 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?

The schema covers 50% of parameters (path has a description; framework has an enum but no description). The description partially compensates by listing the frameworks ('React/Vue/Svelte/plain JS/Flutter') which aligns with the enum, and implies 'path' refers to a .riv file. But it adds no deeper semantics beyond what the schema already conveys.

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: 'Generate ready-to-use integration code' for various frameworks. It explicitly mentions the source resource (.riv file) and distinguishes this tool from sibling tools like riv_inspect or riv_play_state_machine by focusing on code generation, not inspection or playback.

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 no guidance on when to use this tool versus alternatives. It does not mention use cases, prerequisites (e.g., file must exist), or exclusions. The agent is left to infer from the tool name and sibling list, which is insufficient.

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 the output format ('Writes a scene-fragment JSON... returns a rendered preview'), supported elements ('Supports path/rect/circle/ellipse/polygon/polyline/line, nested transforms, style attrs, linear/radial gradients'), and limitations ('Not imported: <text>, <image>, filters, masks'). It doesn't mention overwrite behavior or error handling, but the disclosed behavior goes well beyond the schema.

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 concise (about 80 words) and front-loaded with the primary action in the first sentence. It logically flows from action to output to integration to supported/unsupported elements, with no wasted or redundant phrasing.

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?

The tool has no output schema and no annotations, but the description covers the key contextual needs: what input it accepts, what it produces (scene-fragment JSON and rendered preview), how the output is used (in riv_create), and the supported/unsupported SVG features. It could be more specific about the preview return format, but for a tool of this complexity, the description is largely sufficient.

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%, with all four parameters (svg, svgPath, outSpec, idPrefix) already described in the input schema. The description adds no parameter-specific details beyond the schema, so the baseline of 3 applies. It does connect outSpec to riv_create, but that is not a semantic clarification of the parameter 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?

The description clearly states the tool's function: 'Convert an SVG file (Figma/Illustrator export, icon, illustration) into Rive bezier path shapes' and 'Writes a scene-fragment JSON (shapes with full cubic vertices, gradients, strokes) and returns a rendered preview.' It differentiates from siblings by positioning it as 'the professional way to get high-quality artwork instead of drawing with primitives' and by mentioning integration with riv_create via 'imports.'

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 usage context and exclusions: it is 'instead of drawing with primitives,' tells how to use the output ('Use the fragment in riv_create via imports'), and lists what is not imported with an alternative for text: 'Not imported: <text> (use texts[] with a font), <image>, filters, masks.' This gives clear when-to-use and when-not-to-use 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?

With no annotations, the description takes on the transparency burden. It openly discloses that it uses the official Rive runtime for metadata and direct binary parsing for data binding, and notes that the `dataBinding` field is omitted when absent. This adds meaningful behavioral context beyond a simple 'inspect' claim.

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 all information is relevant and no words are wasted. It efficiently packs a lot of detail into two sentences, though the second sentence is long and could be split for easier reading.

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 there is no output schema, the description provides a solid overview of return contents, listing all major categories and clarifying that data binding is included only when present. It could benefit from mentioning error behavior or file-format limitations, but overall it is sufficiently complete for an inspection tool.

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 already fully documents the single `path` parameter (100% coverage). The description adds no new semantic meaning for the parameter beyond restating that it is a .riv file, so the baseline score of 3 applies.

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 extracts full metadata from .riv files, listing specific content types (artboards, animations, state machines, data binding). This distinguishes it from sibling tools like riv_list or riv_dump by detailing its comprehensive inspection 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 implies the tool is for inspection and full metadata extraction, but it does not explicitly state when to use it over alternatives or mention any exclusions. It gives context about what it covers (including data binding) but lacks explicit 'when not to use' 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?

With no annotations, the description carries the full burden. It clearly states the operation is a 'static diagnostic pass,' implying no file mutation, and lists the specific behavioral scopes it checks (unreachable states, easing discarded, motion-quality rules). This provides useful behavioral context, though it does not mention output format, exit codes, or permissions.

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 front-loaded with the core function and then uses a colon-led list to enumerate checks efficiently. The list is long but each item adds distinct value; the closing sentence about riv_dump is also purposeful. Slightly verbose, but earns its place.

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 single parameter, no annotations, and no output schema, the description is quite complete in explaining what the tool does and what it checks. The only gap is that it doesn't describe the return value format (e.g., a list of issues), which would be expected in the absence of an output schema.

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 input schema already provides 100% coverage for the only parameter ('path' with description 'Path to the .riv file'). The description adds no additional detail about the parameter, so per the rubric the baseline of 3 applies.

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 ('Static diagnostic pass over a .riv file') and enumerates precise diagnostic categories (broken references, oversized assets, unreachable states, etc.). It also explicitly distinguishes itself from the sibling riv_dump by stating it 'complements' it and 'doesn't judge it,' making the tool's purpose unmistakable.

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 names riv_dump as a complementary tool and contrasts it by noting riv_dump shows raw structure but doesn't judge it, giving the agent a clear alternative. However, it does not explicitly state when not to use riv_lint or list other alternatives, so it falls short of a full 5.

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 full burden. It discloses key behavior: recursive traversal, target file type, and reported properties (size and format version). This is sufficient for a simple listing tool, though it does not mention output format or edge cases like permissions or symlinks.

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 concise sentence that covers purpose and output in a clear, front-loaded manner. No wasted words.

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?

The tool is simple with one required parameter and no output schema. The description explains what it reports (size and format version), which is sufficient for invocation. It lacks an explicit output format, but for a listing tool the description is largely 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?

The input schema already documents the 'dir' parameter with a clear description (Directory to search, absolute or relative). The tool description adds the 'recursive' aspect, which relates to behavior rather than parameter semantics. Since schema coverage is 100%, a baseline of 3 is appropriate.

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 recursively finds .riv files under a directory and reports size and format version. It uses a specific verb ('find') and resource ('.riv files'), and distinguishes it from sibling tools like riv_inspect or riv_dump which operate on individual files.

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: use this tool to list .riv files in a directory tree with metadata. It implies a directory-wide search, distinguishing it from siblings that target single files. However, it does not explicitly name alternatives or say when not to use 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, the description carries full responsibility and does so thoroughly. It discloses output contents (groups, shapes, animations, preview, coverage/warnings), that unsupported features are counted in coverage.skipped rather than silently dropped, and that some animations are frozen with a warning. This is highly transparent.

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 long but front-loaded with the core purpose and every sentence contributes substantive detail. It could be improved with structured lists, but it avoids redundancy and only includes necessary information for a complex tool.

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 and absence of an output schema, the description is remarkably complete. It covers input format, output structure, integration approach, supported features, and explicitly delineated limitations, making it self-contained for an agent to use 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 description coverage is 100%, so the baseline is 3. The description adds context about the output format but does not elaborate on individual parameter semantics beyond what the schema already provides. No additional per-parameter meaning is introduced.

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: converting a Lottie JSON into a Rive scene fragment. It names the specific input (bodymovin .json), the output (riv_create scene fragment), and explicitly differentiates from sibling riv_import_svg by noting it preserves animation. This is a specific verb+resource+scope pairing.

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?

Usage guidance is explicit: it contrasts with riv_import_svg ('shapes only'), explains why the 'imports' mechanism is not suitable for animations, and instructs to splice arrays manually. It also lists what is and isn't supported, clarifying when this tool is appropriate and what to expect.

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 full burden and does so comprehensively. It discloses what gets removed (dangling easing interpolators, fired-events, empty tracks), the strict linear-only constraint for thinning, the exclusion of color/id keyframes, opt-in flags, idempotency, and the dry-run behavior. This is rich, unambiguous behavioral 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 description is dense but every sentence earns its place. It front-loads the core purpose, then interleaves constraints, exceptions, and safety guidance with no redundancy or fluff. The structure flows logically from what → safety → usage tips.

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 and lack of output schema, the description covers all necessary context: specific operations, algorithmic caveats (linear-only, no easing shift), parameter semantics, idempotency, dry-run workflow, and follow-up validation. It is complete for an agent to invoke correctly and understand consequences.

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%, providing a baseline of 3. The description adds beyond schema by clarifying that thinning applies only to numeric tracks (KeyFrameDouble) and never to colors or soloActive keyframes, and by tying each boolean to the described removal/thinning steps. This adds meaningful parameter meaning.

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: 'Shrink a .riv without changing its visual output', and enumerates distinct actions (remove unreferenced objects, thin redundant keyframes). It clearly differentiates from siblings like riv_lint and riv_edit by focusing on lossless optimization rather than validation or manual editing.

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 strong usage context: idempotent/safe to run repeatedly, dryRun for planning, and a post-step (run riv_lint afterwards if in doubt). It does not explicitly name alternatives or state when not to use, but the purpose alone makes the intended scenario 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, the description carries the burden of disclosing behavior. It explains the workflow and return type, but it does not clarify side effects of capturing frames (e.g., whether PNGs are written to disk or returned) or error/prerequisite behavior.

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 sentence that front-loads the core purpose and lists key operations without any wasted words.

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?

The description gives a solid overview of the tool and its output, but with no output schema or annotations it leaves gaps: what exactly a 'transition report' contains, how captured frames are delivered, and what the optional rendering parameters (width, artboard, background) do. These would require further inference.

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 covers path, steps, and stateMachine, and the description adds high-level semantic context like 'advance time' and 'capture frames' that maps to step fields. However, width, artboard, and background are undocumented in both schema and description, so the description does not compensate for those.

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 a specific verb ('Run') and resource ('.riv state machine'), and enumerates concrete operations: set/fire inputs, advance time, observe state transitions, and capture frames. This distinguishes it from sibling render/inspect 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 implies an interactive, step-by-step debugging/validation use case and mentions the output ('transition report'), which helps an agent decide when to use it. However, it does not explicitly say when not to use it or name alternative tools.

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 present, so the description carries the disclosure burden. It adds useful behavioral detail such as transparent background by default and full alpha support. However, it does not mention side effects like file creation, output path defaults, or overwrite behavior, leaving some important gaps.

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?

Three focused sentences: the first states the function, the second gives format differentiation and a concrete use case, and the third notes the default transparency behavior. Every sentence earns its place with no 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?

This is a 12-parameter render tool with no annotations and no output schema. The description covers basic purpose and a key differentiator, but omits important invocation details such as output path defaults, state machine vs animation selection, and interactions with transparent/background. It is adequate for tool selection but not for full correct invocation across all options.

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 75%, so the schema handles most parameter meanings. The description adds context around transparency defaults but does not explain undocumented params like height, artboard, or stateMachine. It provides some added value but is not heavily compensating.

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?

Clearly states it renders .riv animations or state machine playback to APNG, naming the exact resource and output format. It also distinguishes itself from GIF by highlighting 24-bit color and alpha transparency, which separates it from sibling tools like riv_render_gif.

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?

Provides a concrete use case comparison with GIF, noting APNG's support for full alpha transparency and GitHub README compatibility, which helps an agent decide when to choose this tool. It does not explicitly exclude alternatives like video or sprites, but the context is strong.

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. It discloses that the image is returned inline and saved to disk, which is a key side effect. However, it does not mention overwrite behavior, file permissions, or that state machine rendering may produce different results than linear animation.

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 short sentences, immediately stating the core function and output behavior. No unnecessary words or 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 a tool with 9 parameters and multiple render siblings, the description is minimal. It covers the basic output behavior but does not explain how to choose between state machine and animation, or how this tool differs from other render tools, leaving some context missing.

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 78%, with most parameters described, but width and height lack descriptions. The description itself adds no parameter-level detail beyond what the schema already provides, so it neither compensates for the gaps nor adds extra meaning.

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 renders one frame of a .riv animation or state machine to PNG, using a specific verb and resource. This distinguishes it from sibling tools like riv_render_gif, riv_render_apng, and riv_render_video that handle animated output.

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 phrase 'one frame' implies use for static captures, but no explicit guidance is given on when to choose this over the animated/render siblings. No alternatives are named and no exclusion criteria are provided.

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 full responsibility for behavioral disclosure. However, it only states the output format and purpose, omitting side effects such as file creation/overwriting, default output location, behavior with missing animations, or performance considerations. This is a significant gap for a tool that writes files.

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 sentence that front-loads the main action and outcome, with no redundant or unnecessary information. It is appropriately concise given the moderate complexity of the tool.

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 has 9 parameters, no output schema, and no annotations, a one-sentence description is insufficient. It does not explain return behavior, output file handling (e.g., default outPath), or the meaning of 'preview' in practical terms. The description is too sparse to fully guide an agent for a tool of this complexity.

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 78%, which is above the 80% threshold, so the baseline is 3. The description adds minimal context by mentioning 'state machine idle playback', which helps clarify the stateMachine parameter, but it does not significantly enhance understanding of the other parameters 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 clearly states the tool renders a .riv animation to an animated GIF, using the verb 'Render' and specifying the resource and output format. It distinguishes from sibling tools like riv_render_frame, riv_render_apng, and riv_render_video by explicitly targeting GIF output, and mentions 'for preview' as the intended use.

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 phrase 'for preview' implies a context of use, but the description does not explicitly state when to choose this tool over alternatives like riv_render_apng or riv_render_video, nor does it mention any exclusions or when not to use it. Thus, usage guidance is only implicit.

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 present, the description carries the full burden of behavioral disclosure. It clearly discloses that the tool writes both a PNG and a JSON metadata file alongside, and reveals the grid layout formula (columns = ceil(sqrt(N))). This adds useful context beyond the schema. However, it does not mention overwrite behavior, file permission requirements, or potential long runtime for large frame counts.

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 long and is front-loaded with the core purpose. It avoids unnecessary jargon and includes only the key details (frame spacing, grid layout, output artifacts). Every sentence earns its place, making it concise and well-structured.

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?

The description gives a good high-level overview but omits important interaction details: how fps, duration, and count interrelate, which parameter takes precedence when both animation and stateMachine are provided, and the effect of width/height on rendering. Since there is no output schema and many parameters are semantically sparse, the description is not fully complete for a tool with 11 parameters.

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 45%, so the description must compensate. It adds meaning for the 'count' parameter (N frames) and the metadata fields (cellW/cellH/cols/rows/count/fps), clarifying how these relate to the output. However, many parameters such as width, height, artboard, animation, stateMachine, and background are not addressed, leaving gaps for the agent. The description only partially compensates for the low schema coverage.

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: 'Render N evenly-spaced frames of a .riv animation/state machine into a single grid sprite sheet PNG'. It specifies the verb (Render), the resource (.riv animation/state machine), and the output format (single grid sprite sheet PNG), which effectively distinguishes it from sibling tools like riv_render_frame, riv_render_gif, and riv_render_video. The output metadata file is also briefly described.

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 the use case (sprite sheet creation) but does not explicitly state when to use this tool versus alternatives. There is no mention of 'use this instead of...' or 'not recommended when...'. Sibling tools such as riv_render_gif and riv_render_video are not referenced, leaving the agent to infer the distinction based solely on the output type.

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 behavioral disclosure burden. It reveals implementation details (canvas.captureStream, MediaRecorder, VP9 fallback) and default duration logic. However, it omits important behavior such as return value, whether it writes to disk, browser/headless environment requirements, and whether existing files are overwritten.

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 purpose, and every clause adds value (format, method, codec, default duration). No filler or 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?

The tool has 10 parameters, no annotations, and no output schema. The description explains core function and duration default but does not cover width/height/artboard/animation/stateMachine semantics, output naming, or return value. For the complexity, the description is incomplete and would leave an agent guessing about half the parameters.

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 50%, so the description must compensate for the five undocumented parameters (width, height, artboard, animation, stateMachine). It adds meaning only for 'duration' by explaining default one-loop behavior and the 2s fallback. No explanation is given for the other undocumented parameters, leaving the agent without sufficient guidance.

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 verb 'Render' and the resource '.riv animation (or state machine)' with a specific output format 'WebM video'. It distinguishes from sibling render tools (gif, apng, frame) by explicitly naming the container format and capture technique.

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 usage for creating WebM videos when a real-time recording is needed, and clarifies default duration behavior. However, it does not explicitly mention when to use this tool over alternatives like riv_render_gif or riv_render_frame, nor does it provide exclusions or prerequisites.

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 full burden. It discloses detailed output behavior: cutout parts via polygons, 2-bone head-tilt mesh, vector eyelid blink, idle/happy animations, state machine with 'happy' trigger, and a preview return. This is substantial, though it doesn't mention failure modes, overwrite behavior, or input requirements beyond 'transparent background recommended'.

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?

Two sentences, highly information-dense and front-loaded. The first sentence packs the full transformation and output features; the second sentence gives actionable follow-up alternatives. No wasted words.

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 complex 9-parameter tool with nested objects and no output schema, the description covers the core pipeline, output features, and sibling tools for refinement. It doesn't mention the nature of the 'preview' or edge cases, but the main workflow is clearly communicated. The schema handles parameter details.

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 67%, and the description adds some semantic context (e.g., 'ears/tail via polygons' hints at the 'parts' parameter, 'head-tilt mesh' links to headRatio/eyes). However, it doesn't explain parameters like artboardWidth/Height or backgroundColor, which remain undocumented in schema. It adds value but doesn't fully compensate for gaps.

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: 'character PNG -> fully rigged .riv' with specific features (cutout parts, head-tilt mesh, blink, animations, state machine). It distinguishes itself from siblings by mentioning 'Fine-tune afterwards with riv_edit or riv_studio', positioning this as the one-call auto-rigging tool.

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 usage for initial rigging from a PNG, with explicit guidance to use 'riv_edit or riv_studio' for fine-tuning. This gives clear context and alternatives, though it doesn't state exclusions (e.g., for non-PNG inputs) or when to prefer other tools like riv_import_svg.

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 behavioral disclosure burden. It discloses that the tool copies files ('copies the bundled skill'), is idempotent ('re-running updates the skill to this server version's copy'), has scope-dependent behavior, and notes the auto-triggering effect. It could be more explicit about overwriting existing skill directories, but 'updates' strongly implies that behavior.

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 front-loaded with the essential action ('One-time setup: copies') and packs critical details into a single well-structured sentence. Every clause adds value: idempotency, scope, default, auto-triggering, recommendation, and alternative. There is no filler 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?

For a simple two-parameter tool with no output schema, the description comprehensively covers what the tool does, when to use it, what behavior to expect (idempotent, scope options), and how to fall back if skill support is unavailable. All essential context is present.

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% — both 'scope' and 'projectDir' are fully described in the input schema. The description repeats these facts (e.g., 'scope=project, default') but adds no parameter-specific meaning beyond what the schema already provides. The baseline of 3 applies because the schema does the heavy lifting.

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: 'One-time setup: copies the bundled `rive-design-guidelines` skill ... into the client's skills directory'. It uses a specific verb ('copies'), names the resource, and explains the effect ('auto-triggers on future Rive work'). This distinguishes it from sibling tools, all of which perform Rive processing or analysis rather than setup.

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 explicitly recommends when to use the tool: 'Recommended on first use of this server in a new environment'. It also provides an alternative for clients without skill support: 'clients without skill support can read the same content via the rive-design-guidelines MCP prompt instead'. This clearly conveys both when to use and when not to use, with a named alternative.

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 full burden of behavioral disclosure. It clearly states that it writes part files and a base.png, mentions that base.png has parts erased, and says it returns bounding boxes for placement. Missing details like overwrite behavior and failure modes leave room for improvement, but the core side effects are well covered.

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 with no filler. The first sentence states the action and purpose, and the second explains outputs and integration. Every phrase adds value, and the structure front-loads the core purpose.

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 no annotations, no output schema, and three parameters including a nested 'regions' array, the description does a solid job covering inputs, outputs, and return value. It could mention prerequisites (e.g., valid PNG, non-overlapping polygons) or error conditions, but it already conveys what the tool does, what it produces, and how it integrates with riv_create.

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 already documents most parameters (pngPath, outDir, polygon, keepInBase). The description adds meaningful semantics by explaining that the 'name' field becomes the filename for each part (<name>.png) and that output is meant for riv_create. This goes beyond the schema's bare property definitions, especially for the 'name' parameter which has no schema description.

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 specific verbs ('Cut polygon regions') and identifies the resource ('character PNG') and purpose ('parts-based rigging (cutout animation)'). It clearly distinguishes itself from the sibling tool riv_create by explaining how the output is consumed ('Use with riv_create: images per part + groups as pivots').

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 usage context by explicitly recommending pairing with riv_create. It doesn't specify when not to use this tool or alternative slicing approaches, but the 'Use with riv_create' workflow provides strong guidance about the intended role in a rigging pipeline.

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 full transparency burden and does so admirably. It discloses key behaviors: 'Only one studio runs at a time,' 'hot reload on file change,' 'auto-generated state machine input controls,' 'event log,' and the 'Instructions for AI' box. It also mentions that re-running create/edit updates the browser instantly, which is a non-obvious behavior.

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 front-loaded with the core purpose. Every sentence adds a useful detail (features, limitations, companion tools). It could be broken into bullets for easier scanning, but no sentence is wasted and the length is justified given the tool's complexity.

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 and lack of output schema, the description covers most relevant aspects: features, live behavior, single-instance limitation, and connection to other riv_* tools. It does not explicitly state what the tool returns (e.g., the local URL), which would be helpful for an agent, but it covers the essential context for selecting and invoking the tool.

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 description doesn't need to restate parameter basics. It adds value for scenePath by explaining it 'enables the edit+rebuild panel' and mentions the watched path. The `stop` parameter is not described in prose, but the schema description already covers it. The added scenePath context pushes it above the baseline of 3.

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: 'Start a local web UI... for live-previewing and editing a .riv file.' It clearly differentiates the tool from siblings like riv_render_frame or riv_edit by emphasizing interactive editing, timeline, hot reload, and auto-generated controls. The rich feature list makes 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 provides clear context for when to use the tool—for interactive preview and editing—and even references companion tools: 'Re-running riv_create/riv_edit on the watched file updates the browser instantly' and 'fetch those with riv_studio_notes.' However, it does not explicitly name alternatives or say when not to use it, so it falls short of a 5.

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 full burden and does so excellently: it discloses that reading consumes the queue, that the Studio shows messages as picked up, that both operations can be combined in one call, and that the reply appears as the assistant's message. This goes well beyond a basic statement of function.

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 longer than average but every sentence earns its place. It is front-loaded with the core purpose (two-way chat), then structured into READ and REPLY sections with precise, actionable details. The use of numbered items and examples makes it easy to scan.

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 no annotations and no output schema, this description is highly complete. It covers both modes, when to trigger, queue consumption behavior, follow-up actions, the requirement to always reply, and the option to combine read/reply in one call. No critical gap is apparent.

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 baseline is 3. The description adds meaning beyond the schema by explaining that omitting `reply` triggers the read mode, that `reply` posts into the chat, and that passing `reply` together with read clears and retrieves new messages. It does not mention `peek` explicitly, so not a full 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 states the tool is for both reading and replying to the Studio chat, with an explicit two-mode structure. It distinguishes itself from sibling tools by describing the unique read/reply behavior rather than rendering or editing operations.

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?

Provides explicit triggers ('check the studio notes', after opening riv_studio when the user leaves notes) and explains when to call with and without the `reply` parameter. It also names follow-up actions (riv_edit or riv_create) and stresses that replying is mandatory, giving clear usage 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?

With no annotations provided, the description carries the full burden. It discloses forced identical output size, thresholding behavior, and the exact visualization color scheme (red/dim), adding context beyond the schema. It does not cover failure modes or requirements like matching artboards, but provides solid behavioral insight.

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 action, and every clause adds value. There is no redundancy or fluff, making it highly concise and well-structured.

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 11-parameter tool with no output schema, the description explains the core behavior and return values but leaves background and stateMachine parameters unexplained. It gives a good baseline but does not fully document all configuration options, especially optional selectors.

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 45%, so the description compensates by clarifying that artboard, animation, and time parameters select the rendering context, width/height are forced to identical sizes, threshold controls matching strictness, and out specifies the PNG path. It does not explain background or stateMachine, but most parameters are implicitly covered.

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 renders two .riv files under identical conditions and computes a thresholded per-pixel visual diff, explicitly listing output contents (match rate, pixel count, diff PNG). The phrase 'visual diff' differentiates it from sibling tools like riv_diff and riv_ab_compare.

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 strongly implies usage for comparing visual output of two .riv files but does not explicitly state when to choose this tool over alternatives or provide exclusions. It lacks direct references to riv_diff or riv_ab_compare, so the guidance is implied rather than explicit.

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