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 the full burden and does a good job: it discloses the external network dependency on api.iconify.design, that the SVG is downloaded and imported into Rive, and that output matches riv_import_svg. It leaves unspecified whether the import mutates the active document or only writes the outSpec file, and says nothing about network failure or rate-limit 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?

Three short sentences, front-loaded with scale and purpose, then modes, then the environment prerequisite. Every sentence adds information; nothing is repeated from the schema or title.

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 5-parameter, annotation-free, no-output-schema tool, the description covers purpose, mode selection, network requirement, and return-shape parity with a sibling. The remaining gap is what exactly happens to the target Rive document on import, which matters for an agent deciding whether this is a safe read or a mutation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema cannot express: which parameters form which mode and that icon+outSpec are jointly required for the import path. Defaults and formats are already in the schema, so no further compensation is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Search Iconify's ~200k ... icons') plus the conversion behavior, and separates itself from riv_import_svg by declaring output parity. The dual-mode framing lets an agent distinguish the search-only and fetch-and-import paths without opening the schema.

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 lays out the two operating modes and the parameter combinations that select them ('query-only returns ...', 'icon+outSpec downloads and imports'), and states the network prerequisite. It stops short of an explicit when-to-use-this-vs-riv_import_svg rule, though 'same output as riv_import_svg' implicitly routes local-SVG cases to the sibling.

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 behavioral burden and does so well: sequential rendering on one headless Chromium page, no parallel pages, no watch mode, per-job failure isolation, and report entries for every job/file. These are exactly the operational traits an agent needs before invoking it.

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 well front-loaded, starting with what the tool renders before moving to execution and failure semantics. Most sentences earn their place, though the long paragraph could be slightly easier 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 complex nested-job tool with no output schema, the description is complete enough: it explains batching, defaults merging, format requirements, failure behavior, and the shape of the returned report entries. An agent has what it needs to call 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 100%, so the schema already documents the parameters thoroughly. The description adds meaningful semantics beyond it: defaults are merged under each job with job-level values winning, and every job needs a format either in the job or in defaults.

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 states a specific verb and resource: batch-render a list of .riv jobs to png/gif/apng/webm/sprites. It clearly distinguishes this batch tool from single-file rendering siblings by emphasizing lists, globs, and one-call batching.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear usage context: built for CI/scripts and meant to be called repeatedly, with no live watch mode. It does not explicitly name single-render siblings as alternatives, but the batch-vs-single distinction is implicit and usable.

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 well: it discloses that the file is validated against the official runtime, that a rendered preview frame is returned, that PNG paths resolve relative to cwd, that z-order favors later array entries and images over shapes, and that the Canvas2D preview will not play audio even though the AudioAsset is written correctly. It never states what happens when outPath already exists (overwrite vs error) or how invalid specs fail, which keeps it short of a 5 for a file-writing mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is long, but the complexity of the scene spec justifies most of the volume, and the core purpose and return value are front-loaded in the first line before any examples. Minor waste remains — rotation units are stated twice, and the trailing bullet sprawl (layouts, mesh, followPath, groups, imports, pro features, audio) is appended rather than organized into a scan-friendly outline.

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 3-parameter tool with no output schema and a 100%-covered top level but wide-open nested scene object, the description supplies everything an agent needs: two contrasting worked specs (graphics and character rig), preset catalog, pro-feature syntax, import behavior, z-order rules, and the audio limitation. No material invocation detail is 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?

Top-level schema coverage is 100%, but the scene object is declared with additionalProperties:true and only layouts is actually documented, so the description must supply the real semantics — and it does, in depth, for shapes, animations, tracks, presets, groups, mesh vertices, followPath, imports, and audio events. It falls short of 5 because much of the meaning is conveyed by worked examples rather than enumerated fields, leaving some sub-keys (e.g. keyframe field options, state machine inputs) inferential.

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 opening sentence states a specific verb and resource ('Create a working .riv animation file from scratch') plus the distinguishing value proposition ('no Rive editor needed') and the side effect of runtime validation returning a preview frame. This clearly separates it from riv_edit, riv_import_svg, and other siblings that operate on existing 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?

It gives an explicit recommended pipeline ('riv_design_tokens → riv_import_svg / riv_asset_search → riv_create → riv_critique → fix → re-critique') that tells the agent both when to use this tool and which siblings precede and follow it. It also states a preference rule ('PREFER imported real vector art over drawing with primitives') and directs the agent to the rive-design-guidelines prompt for non-trivial scenes.

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 well: it discloses all five return artifacts and what each is for (onion skin for trajectories/direction vs facing, motion vectors computed from file data, objective metrics + lint). It stops short of stating cost/failure behavior (e.g. what happens if the path is invalid or the scene has no animation), which keeps it below a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the one-line purpose, then a numbered enumeration of returns, then the workflow imperative. Dense but every sentence earns its place — no restating of the tool name, no 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 7-parameter, no-output-schema tool, the description covers the return surface thoroughly and tells the agent the decision procedure. The remaining gap is that only one of the seven checklist axes ('spatial/directional coherence') is named, so the agent cannot pre-anticipate the scoring rubric without the call result.

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 every parameter (path, width, frames, artboard, animation, stateMachine, individualFrames) is already documented with defaults and ranges. The description only adds the 'N frames left→right' framing and doesn't clarify precedence between animation and stateMachine or the token tradeoff of width/frames, so baseline 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?

States a specific verb and resource ('One-call review bundle for the render→critique→revise loop') and enumerates exactly what it returns: filmstrip, onion skin, motion report, metrics/lint, and a 7-axis checklist. This clearly separates it from siblings like riv_lint, riv_visual_diff, and riv_render_gif, which each cover only a slice of this bundle.

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 frames the when ('render→critique→revise loop') and the when-next ('score each axis 1-5, fix anything below 4 (riv_edit / regenerate), then re-run'). It even names the alternative tool to use for fixes and sets a minimum iteration count ('at least twice'), leaving almost no scheduling inference to the agent.

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?

No annotations are provided, so the description carries the full burden. It discloses determinism, what each generated group contains (OKLCH palette with WCAG ratios, gradient pairs, motion roles, scales), and the strict usage contract. It does not explicitly state side effects or permissions, but the generative read-only nature is strongly implied.

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 front-loaded: first sentence states what is generated, second states the critical usage contract, third summarizes inputs. Every clause earns its place and no filler is present.

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?

There is no output schema, so the description must explain return values, and it does so at the category level (palette, gradients, motion, scales, type). It lacks exact output shape or pagination-style details, but is complete enough for an agent to know what to expect and how to use the result.

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%, and the schema already documents mood, seed, and scheme with defaults. The description lists the same inputs and the mood enum, adding only minor framing ('optional seed color') beyond the structured schema, so baseline 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?

States a specific verb (generate) and resource (design tokens) with clear scope: palette, gradients, motion, spacing, type. It explicitly distinguishes itself from sibling riv_create by saying it must be called before scene creation.

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 says to call this first, then to use ONLY the returned values and never invent raw hex colors or ad-hoc durations. It also names the downstream sibling riv_create, leaving no ambiguity about ordering or alternatives.

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 burden. It discloses what the diff reports (type counts, per-object property diffs), which is real behavioral content, but says nothing about read-only semantics, error behavior on invalid/mismatched files, or that the per-object list is truncated.

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?

A single front-loaded sentence that names the resource, the operation, and the two comparison axes with no filler. Nothing to trim and nothing buried.

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 and its parameters are fully documented in the schema, but with no output schema the description should convey the return shape more concretely. It hints at result content (count deltas, property differences) yet omits result structure and truncation behavior.

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 pathA/pathB/maxDiffs are already documented, and the baseline of 3 applies. The description adds no meaning beyond the schema — notably it never mentions that the per-object diff list is capped by maxDiffs (default 30), which is the one non-obvious parameter behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (structural diff of two .riv files) plus the exact dimensions compared: type count changes and per-object property differences. This implicitly separates it from riv_visual_diff, but the sibling is never named, so an agent must infer that 'structural' excludes rendering/pixel comparison.

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 no when-to-use guidance, no prerequisites (are the files required to be valid/parsable?), and no explicit routing to alternatives. With riv_visual_diff, riv_ab_compare, and riv_inspect in the sibling set, the absence of any exclusion or selection criteria leaves the agent to guess.

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 and does much of it: it discloses that deletes trigger automatic subtree and reference remapping, that a preview is rendered, and that edits apply in order. It leaves gaps around failure behavior (partial application on error), overwrite risk confirmed only via the schema's outPath default, and what the preview actually 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?

Front-loads the operation inventory in sentence one, then spends the second paragraph exclusively on the most complex op (setKeyframes), which is the right allocation of space. It is dense with long parentheticals and could be split into a short bulleted op list, but no sentence is wasted.

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 nested, multi-op mutation tool with no annotations and no output schema, the description covers the operation taxonomy and the hardest sub-mode in usable depth. Remaining gaps are error/atomicity semantics and what the rendered preview contains — meaningful but secondary for a call to succeed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics: rotation is in degrees, mode=replace swaps the whole track vs add appends/creates, and remove deletes by frame number while ignoring value/easing. The schema's own enum descriptions for mode and keyframes are terse, so this materially improves correct invocation.

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?

Opens with a specific verb+resource ('Modify an existing .riv') and immediately enumerates the four supported operations (set, setText, delete, setKeyframes), which maps directly onto the op enum. It is clearly distinguishable from riv_create (new file) and riv_dump (read-only inspection), which it explicitly references as the companion lookup 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?

Gives a concrete prerequisite and routing instruction: use riv_dump to find object indices/names before editing, and notes the roundtrip is lossless. It does not state explicit when-not conditions (e.g. when to prefer riv_create vs this, or when to use riv_optimize afterwards), so it stops short of full alternative routing.

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 zero annotations, the description carries the full burden, and it does add real value by disclosing that the result reports unsupported/approximated features and whether pixel comparison was available — non-obvious fidelity caveats for a Lottie exporter. However, it never states that the tool writes a file to disk, what happens if the output path already exists, or what the "all unsupported" annotation on the animation parameter means for callers.

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 tight sentences, front-loaded with the action and format, followed by what the result reports. Nothing is wasted and nothing is buried.

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 five fully documented parameters and no output schema, the description usefully explains what the response conveys (unsupported/approximated features, pixel comparison availability). The remaining gap is the file-write side effect and its overwrite/error semantics, which an agent needs before pointing the tool at a real path.

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 every parameter (fps, out, path, artboard, animation) is already documented with defaults. The description adds only the "one animation at a time" scoping constraint and otherwise restates the schema, so baseline 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?

States a concrete verb+resource+target format ("Export one .riv animation to Lottie JSON"), which cleanly separates it from render-oriented siblings like riv_render_video or riv_render_gif. It doesn't acknowledge the near-neighbor sibling riv_lottie_import or state the inverse relationship, so the differentiation is inferred rather than declared.

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?

There is no "use this when..." clause, no exclusions, and no mention of alternatives such as riv_render_video for visual output or riv_dump for raw data. The agent must infer the conversion use case entirely from the one-line purpose.

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 disclose one meaningful behavioral trait — the generated code uses the file's real artboard, state machine and input names rather than placeholders. However it never says whether code is returned inline or written to disk, whether it overwrites anything, or what permissions are needed.

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?

A single front-loaded sentence with the verb, output type, and resource; nothing is wasted and the framework list is compact.

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?

Both required parameters are well covered by the schema, but with no output schema and no annotations, the description should clarify the return shape (code string vs. written file, where it lands). That missing piece leaves an agent unsure what to expect after the call.

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 both `path` and `framework` (with its enum) are already fully documented in the schema. The description adds only the framing that the file's real names drive generation; it adds no syntax or format detail beyond the schema baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb+resource: 'Generate ready-to-use integration code ... for a .riv file', with the supported frameworks enumerated. It is clearly distinguishable from render/inspect/edit siblings, though it does not explicitly name what it is not.

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 is only implied by the verb and resource — an agent can infer this is what you call when you need integration code for a .riv file. There is no explicit when-to-use/when-not guidance, no mention of prerequisites such as the file existing or being inspected first, and no routing to siblings like riv_inspect.

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 provided, the description carries the full behavioral burden and does so thoroughly: it discloses that the tool writes a scene-fragment JSON, a rendered preview, and a coverage/warnings summary; that skipped features are counted rather than silently dropped; and that some unsupported features are frozen with warnings.

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 purpose and remains information-dense, but it is a single long paragraph with several dense clauses. The supported/unsupported lists earn their place, though bullet-like structure would improve scanability.

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 import tool with no annotations and no output schema, the description is complete enough: it explains the output artifact, preview and warning side effects, supported and unsupported feature coverage, and how to consume the generated fragment.

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 input schema already documents all four parameters. The description does not add parameter-specific syntax or constraints beyond what the schema provides, making the baseline 3 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 states a precise verb and resource: convert a Lottie/bodymovin JSON animation into a riv_create scene fragment. It immediately distinguishes itself from riv_import_svg by noting that this tool preserves keyframed timing rather than importing shapes only.

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 explicitly contrasts this tool with riv_import_svg, explains that the resulting fragment must be spliced into a riv_create scene spec rather than used through 'imports', and lists unsupported Lottie features that will be skipped. This gives clear routing and usage context.

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 meets it: it names precisely what is destroyed (dangling easing interpolators, fired-events with no referrers, empty keyframe tracks), what is explicitly protected (colors, soloActive id-keyframes, any run touching hold/cubic easing), and why no easing shifts. It also declares idempotency and safety to repeat, plus the dryRun non-destructive path.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the benefit and the mechanics, and every clause is load-bearing. It is dense and the parenthetical citation of keyed_property.cpp semantics is somewhat academic overhead, but it justifies the linear-run restriction rather than padding.

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 mutating file-rewriting tool with no annotations, no output schema, and an overwrite-by-default outPath, the description covers safety, destructiveness, idempotency, preview mode, and a verification path via riv_lint. There is no output schema to explain, and nothing an agent needs before invoking it is 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 coverage is 100%, so baseline is 3, but the description adds real semantics beyond the schema: the booleans are a uniform 'on by default, set false to skip' contract, and the tolerance is scoped to linear-only runs so an agent understands it cannot affect eased segments. It does not discuss outPath overwrite behavior or the interaction between thinKeyframes and removeUnreferenced when both are false.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb and resource ('Shrink a .riv') and immediately bounds the claim with 'without changing its visual output', then enumerates the two exact operations (removing unreferenced objects, thinning keyframes on linear runs). No sibling tool does lossless shrinking, and the description makes that unique role 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?

Gives clear operational guidance: each boolean is on by default, set to false to skip, use dryRun=true to preview, and 'Run riv_lint afterwards if in doubt' — an explicit follow-up with a named sibling. It does not name a condition under which a user should skip the tool entirely or prefer a different sibling, which keeps it just 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 behavioral burden. It discloses the execution flow and that a transition report is returned, plus optional frame capture, but it does not clarify side effects, whether the .riv file is modified, permission requirements, output format, or constraints such as step 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 a single front-loaded sentence that lists the key actions and return value without waste. Every clause contributes to understanding the tool's operation.

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 covers the core workflow and return value at a high level. Given the tool's complexity (six parameters, nested steps, no output schema, and no annotations), it leaves gaps around step execution semantics, output structure, and behavioral constraints, but is minimally adequate for an agent to attempt 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?

Schema description coverage is 100%, so the input schema already documents all six parameters and the nested step fields. The description adds a high-level mapping of inputs, advancement, and capture to the step workflow, but no syntax or constraints 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 states a specific verb and resource: it runs a .riv state machine step by step, with set/fire inputs, time advancement, transition observation, and optional frame capture. It is clear what the tool does, but it does not explicitly distinguish itself from render-oriented siblings such as riv_render_frame or 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?

Usage is implied by the step-by-step interaction model and the optional frame capture, which suggests it is for scripted state-machine playback rather than static rendering. However, it gives no explicit when-to-use, when-not-to-use, or named alternatives among the many sibling 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?

With no annotations, the description must carry the behavioral burden. It does disclose the mechanism ('inspect the file with bundled official WASM') and the outcome taxonomy (unsupported / conditional / unverified), but it never states that the operation is read-only, whether it fails or succeeds on mismatches, or how 'documented minimums' are determined.

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, no filler, with the core capability front-loaded and the WASM implementation note trailing. Slightly dense phrasing ('report unsupported, conditional, or unverified support') but every clause carries 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?

With no output schema, the description needs to convey what comes back; it lists the three support classifications but does not describe the report shape, whether results are per-target/per-feature, or whether an incompatible file yields an error versus a report. Adequate but leaves real gaps for a 4-parameter tool with nested objects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds mild value by framing targets/versions as optional comparisons against documented minimums, and the 'unverified' category relates to the strict flag, but it does not directly explain what each parameter changes.

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 names specific verbs and resource: detect .riv features, compare against documented minimum runtime versions, and report support status. This is clearly a compatibility preflight, not a generic inspection. It doesn't explicitly differentiate from close siblings like riv_lint or riv_inspect, which keeps it at 4.

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 'preflight' framing and 'optional target runtime versions' imply usage before targeting a runtime, but there is no explicit when-to-use or when-not-to-use statement, and no named alternative (e.g., riv_lint for general correctness checks). Usage is inferable rather than stated.

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 disclosure burden; it usefully notes frames default to a transparent background and explains the transparency/background relationship. However it omits write-side behavior: that it writes a file to disk, overwrite semantics, and any setup/dependency requirements, which matters for a render-and-save tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with zero filler, leading with what it does and the format's key differentiator before the background note. Every clause 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?

For a 12-parameter render tool with no output schema, the description adequately conveys the core capability and a key default. It could be slightly fuller on output file placement and state-machine precedence, but nothing critical for invoking it is 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 coverage is 100%, so all 12 parameters including defaults are already documented in the schema. The description only reinforces the transparent-background default and adds no format or interpretation detail beyond the structured fields, so baseline 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?

States a specific verb (render) and resource (.riv animation or state machine) to a precise output format (APNG). It explicitly contrasts with GIF, letting an agent distinguish it from riv_render_gif without opening a schema.

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?

Explains the selection rationale versus GIF (24-bit color, alpha transparency, GitHub README animation) which gives clear context for when to choose this format. It does not name other siblings like riv_render_video or state explicit when-not conditions, so it stops short of full routing 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 behavioral burden. It does disclose the useful dual behavior of returning the image inline AND writing a file to disk, which is real value beyond the schema. However, it omits whether an existing file at outPath is overwritten, what happens on invalid animation/stateMachine names, and any permission or side-effect warnings for a tool that writes to disk.

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, zero waste, with the core action front-loaded and the output behavior summarized second. Nothing is padded or repeated from the title.

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 nine-parameter tool with full schema coverage and no output schema, the description covers what the tool produces (inline image plus file on disk), which is the main gap an output schema would otherwise fill. Overwrite/error semantics are the remaining omission, keeping it short of a 5.

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 every one of the nine parameters is already documented with defaults and constraints; baseline 3 applies. The description adds only the passing mention of 'animation or state machine' and no detail on time, artboard, background, or the stateMachine-over-animation precedence that the schema encodes.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — render one frame of a .riv animation or state machine to PNG. The 'one frame' qualifier implicitly separates it from the sibling renderers (riv_render_gif, riv_render_apng, riv_render_video, riv_render_sprites, riv_batch_render), though no sibling is named explicitly.

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 is implied by 'one frame' versus the animated-format siblings, but the description never states when to prefer this over riv_render_gif or riv_render_sprites, nor any prerequisites such as the .riv file needing to exist. The agent must infer the choice from sibling names alone.

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 burden, and it discloses very little. It never states that rendering writes a file to disk, whether an existing outPath is overwritten, how long the render blocks, or what happens when the named artboard/animation is missing. The only real behavioral hint is "for preview."

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?

A single front-loaded sentence with no filler and the key resource and output format stated first. It is efficient, though the terseness is part of why behavioral context is thin.

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 9-parameter rendering tool with no annotations and no output schema, so the description must explain the result of the call. It says nothing about whether the tool returns the written GIF path, whether output is silent, or how errors for invalid artboard/animation names surface, leaving a real gap for a file-producing 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 description coverage is 100% with per-parameter defaults and bounds, so the schema already does the explanatory work. The description adds only the notion of "state machine idle playback," which loosely maps to the stateMachine/animation parameters, so baseline 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 names a specific verb (render) and precise input/output (a .riv animation or state-machine playback to an animated GIF). It is clear on its own, but it never distinguishes itself from near siblings such as riv_render_apng, riv_render_video, or riv_render_frame, so an agent must infer the choice from names alone.

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?

"For preview" implies a lightweight, quick-look use case, which is a genuine usage signal. However, there is no explicit when-to-use/when-not, and no routing to GIF vs APNG vs video vs single-frame rendering, which is exactly the decision an agent faces with this sibling set.

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 disclose the key side effect: it writes a PNG plus a JSON metadata file next to it, and even names the metadata fields. However, it never states overwrite behavior for existing files, failure modes (bad path, missing artboard/state machine), or whether the operation is idempotent — gaps that matter for a write-to-disk tool with zero annotation coverage.

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 compact sentences with the artifact and layout rule front-loaded, and the side-effect file is noted immediately after. Dense but every clause carries information; only the parenthetical formula mildly interrupts the flow.

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, annotation-free tool with no output schema, the description covers the essentials: what is produced, where it lands, and the default grid behavior, while the schema fully documents each parameter. The only meaningful omission is write-side behavior (overwriting existing output) and error conditions.

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 baseline is 3 and the schema already documents every parameter including defaults and bounds. The description adds only the grid formula and confirms the JSON metadata contents (cellW/cellH/cols/rows/count/fps), which is marginal value on top of a fully documented schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (render), a precise resource (grid sprite sheet PNG), and the exact output composition (N evenly-spaced frames, grid laid out by ceil(sqrt(N))). This clearly distinguishes it from riv_render_frame, riv_render_gif, riv_render_apng and riv_render_video, which produce different artifacts.

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 output format implies when to use it (you want a sprite sheet rather than a GIF/APNG/video), but no sibling is ever named and there is no explicit when/when-not guidance. An agent must infer the choice from the artifact description alone, which is implied usage rather than stated routing.

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 whole burden and does add real behavior: the captureStream/MediaRecorder mechanism, VP9 with VP8/generic-webm fallback, and the duration fallback rule (2s for bare state machines or undeterminable length). It stops short of stating whether rendering requires a headless browser, whether existing output files are overwritten, or roughly how long the operation takes.

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 dense sentences, front-loaded with the core action and output format, then the implementation and defaulting rules. No filler and nothing that could be cut without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter, annotation-free tool with no output schema, the description covers the mechanism and key defaults but says nothing about the return value (e.g., whether it returns the written path), the cost/latency of rendering, or any environment prerequisites. Adequate but noticeably incomplete for 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 100%, so the baseline is 3. The description only re-states defaults already documented per-parameter (duration, animation vs. stateMachine precedence) rather than adding syntax, formats, or constraints beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Render') plus the resource (a .riv animation or state machine) and the exact output artifact (real-time WebM video), which cleanly separates it from riv_render_gif, riv_render_apng, riv_render_frame and riv_render_sprites without needing to name them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The WebM output format implies when to choose this over the GIF/APNG/frame siblings, but no alternative is named and no conditions or exclusions are given. The only explicit guidance is about defaults (duration, animation vs. stateMachine precedence), not about tool 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 burden and does real work: it discloses the per-change pixel comparison, that visual changes are skipped with reasons, that the result is validated before writing, and that dryRun never writes. This is substantive safety/behavior context beyond a bare 'repair' verb; only failure modes and what the validation report contains are left open.

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 short sentences, each carrying distinct information (procedure, per-change policy, dryRun guarantee), with the core action front-loaded. No 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 4-param mutation tool with no annotations and no output schema, the description covers process, safety of writes, and dryRun behavior well. It stops short of describing the returned result or how skipped changes are reported, which an agent calling it blind might want.

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 schema already documents path, out, fixes, and dryRun, including the 'source is never overwritten' guarantee. The description reinforces dryRun semantics ('dryRun never writes') but adds no syntax, defaults, or interaction details beyond the schema — baseline 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 names a specific verb and resource — 'Repair lint findings' — and scopes it to 'one change at a time', which separates it from the detection-side sibling riv_lint. It never names a sibling explicitly, so the differentiation is implicit rather than stated.

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 is implied (run after lint, one fix at a time, skip visual changes) but there is no explicit 'use this when / use riv_edit or riv_optimize instead' routing. An agent must infer the position in the workflow from the mention of 'lint findings'.

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 substantial work: it discloses the rig structure produced (polygon cutouts, seamless 2-bone head mesh, vector eyelids), the animation set, and that a preview is returned. The notable gap is write-safety behavior — nothing says whether outPath is overwritten or what happens if it already exists, which matters for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The output pipeline is front-loaded ("One call: ...") and nearly every clause adds a concrete capability rather than filler. It is a long run-on sentence with several comma-separated clauses, which slightly hurts scannability, but there is no wasted content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter, nested-object tool with no annotations and no output schema, the description explains the produced .riv well but is thin on returns — "Returns a preview" doesn't say whether that is an image, a frame, or a path. The pipeline coverage is good; the response-side and overwrite behavior leave gaps an agent may need to discover at call time.

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 every parameter (eyes, parts, furColor, headRatio, artboard size, background) is already documented in the schema, including the pivot default and behindBody semantics. The description only echoes 'ears/tail via polygons' without adding format or constraint detail beyond the schema, so the baseline 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 names a specific verb+resource (auto-rig a character PNG into a fully rigged .riv) and enumerates the produced artifacts: cutout parts, head-tilt mesh, vector blink, idle/happy animations, state machine. This is unmistakably distinct from siblings like riv_create or riv_edit, which the agent can rule out without opening schemas.

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?

"One call" frames this as the one-shot automated path, and "Fine-tune afterwards with riv_edit or riv_studio" explicitly routes post-processing to the correct siblings. It stops short of stating when *not* to use it (e.g. when an existing .riv should be extended rather than regenerated), so it isn't fully 5-level guidance.

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

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

No annotations are provided, so the description carries the 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 behavioral burden. It usefully discloses file outputs (each part as <name>.png plus base.png with erased parts) and bbox returns, but omits overwrite behavior, error conditions, and permission requirements.

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 with zero waste, front-loaded with the core action and followed by output behavior and integration guidance. Every sentence 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 rich input schema and no output schema, the description adequately explains what is produced and returned (part PNGs, base.png, bboxes). Minor gaps around overwrite/error behavior remain, but an agent can call 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 description coverage is 100%, so the schema already documents all three parameters. The description adds minor context about output naming and base erasure, but does not add syntax or format details beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource: cut polygon regions out of a character PNG for parts-based rigging. It is clear what the tool does and what artifacts it produces, though it does not explicitly distinguish itself from potentially similar sibling tools such as riv_extract_assets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear usage context: parts-based rigging and use with riv_create for images and pivots. It does not state when to avoid this tool or name alternatives, but the intended workflow is explicit.

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 add useful behavior: hot reload, live-applied edits, the one-studio-at-a-time limit. But key operational facts are missing — whether the call blocks until stopped, what it returns (a URL? a port?), what happens on port conflict, and that stopping requires the separate stop flag. The LAN-sharing security caveat lives only in the schema, not the description.

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?

Purpose is front-loaded in the first clause, followed by a capability list and then the sibling pointer and the singleton constraint. The feature enumeration is long but each item is substantive rather than filler; only the parenthetical layout description is arguably decorative.

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 7-parameter, long-running server tool with no annotations and no output schema, the description covers what the UI offers and points at riv_studio_notes, but omits lifecycle and return-value essentials an agent needs to invoke it correctly — blocking behavior, the URL/port it yields, and how stop interacts with a running instance.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all seven parameters including share, shareHost, sharePort and stop. The description only adds meaning for scenePath ('with scenePath, direct scene-JSON editing'); it says nothing about port, stop, or the share trio beyond the schema. Baseline 3 is appropriate when 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?

States a specific verb and resource ('Start a local web UI ... for live-previewing and editing a .riv file') and enumerates the concrete capabilities (hierarchy tree, inspector, timeline, hot reload, state-machine controls, scene-JSON editing). It also names the sibling riv_studio_notes and what that sibling is for, so an agent can separate the two without opening either schema.

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?

Gives real usage context: re-running riv_create/riv_edit on the watched file refreshes the browser, and the riv_studio_notes box should be fetched separately. It also states the singleton constraint ('Only one studio runs at a time'). It never explicitly contrasts with alternatives such as riv_render_frame or riv_inspect, so it stops short of full when/when-not 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 burden and does so: it discloses the non-obvious side effect that a read consumes the queue and shows as 'picked up' in the Studio, and that edits hot-reload the browser. It does not cover failure behavior (Studio not running, wrong port) or that peek avoids consumption — that detail lives only 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?

Numbered READ/REPLY structure with the mode selection front-loaded is easy to scan and the closing sentence about combining both modes is useful. A few sentences are slightly repetitive ('Always reply: without a reply the user cannot tell whether you acted'), but nothing is wasteful.

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?

No output schema exists, and the description adequately says what a read returns (messages the user typed) and what a reply produces in the chat. Combined with full schema coverage this is close to complete; the omission of `peek` semantics in prose is the only real 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?

Schema coverage is 100%, so baseline is 3; the description earns above that by explaining what `reply` should contain (short summary of changes and anything skipped) and that read+reply can be combined in one call. `peek` and `port` are left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb pair (read / reply) against a specific resource (the Studio web UI's Agent chat), and the two numbered sections make the dual purpose explicit. An agent can immediately tell this apart from riv_studio, which merely opens the UI, without opening either schema.

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?

Gives literal trigger phrases in two languages ('check the studio notes' / 「スタジオの指示を確認して」), a situational trigger (after opening riv_studio when the user left notes), and names the follow-up siblings (riv_edit, riv_create). It also mandates always replying, closing the main failure mode of silently acting.

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 well: it discloses the return shape, coordinate accuracy, renderMode semantics, renderRisk behavior, SVG handling, font substitution and bake-with-warning behavior, Figma token requirements, and that it writes an overlay PNG. These are substantial behavioral details 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 purpose is front-loaded and the text is dense but mostly earns its place by explaining complex output and mode behavior. It is a long single paragraph with several parentheticals, so it is not maximally concise, but the length is justified for a tool with this much behavioral nuance.

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?

There is no output schema and no annotations, so the description must carry the return-value and behavioral contract. It explains the nested element tree, overlay PNG, accuracy, independent renderMode and semanticHint fields, vector-source behavior, and font warnings, leaving no major ambiguity for 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?

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful selection and behavior semantics for svgPath, fonts, and the vector-vs-screenshot mode, though it does not add much beyond the schema for minArea, maxElements, or overlayPath.

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: find rectangles, text runs and images in a UI screenshot or design comp. It clearly distinguishes the tool from downstream tools by stating it is geometry only and does not know a button from a card, and it names riv_ui_prototype as the next step.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit selection guidance: use svgPath instead of imagePath when a vector source exists, with different behavior clearly described. It also names the downstream tool riv_ui_prototype and explains that this tool only extracts geometry, so the agent knows when to use it and when to hand off.

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 behavioral burden and does well: it explains role-driven shape/image creation, entrance animations, hover/press states, fallback behavior for unassigned elements, and how svgPath preserves editable text/images. It stops short of covering overwrite behavior for outPath, failure modes, or what the call returns beyond producing a .riv.

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 action and workflow, then moves to roles, path constraints, and svgPath/figmaUrl behavior. It is dense but appropriately sized for a complex 12-parameter tool, with little wasted text, though the long role list and packed sentences reduce readability slightly.

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 mutation tool with no annotations and no output schema, the description is largely complete: it covers purpose, required prior-step alignment, role mapping, input exclusivity, svgPath semantics, and FIGMA_TOKEN requirements. It could be stronger by stating the actual return value or outPath overwrite behavior, but the essential invocation 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 coverage is 100%, so the schema already documents each parameter, but the description adds important semantics beyond it: exactly one of imagePath, svgPath, or figmaUrl must be passed, the same one used in riv_ui_detect, and minArea/maxElements must match across calls. It also explains role assignment and the generic-panel fallback, though it does not clarify every behavioral parameter such as stagger, ambient, or entranceMs.

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 states a specific verb and resource: taking elements from riv_ui_detect, assigning roles, and producing an animated .riv file. It clearly distinguishes this prototyping step from the upstream detection call and from generic creation/import siblings by naming the source tool and the resulting artifact.

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 the intended workflow after riv_ui_detect, requiring the same imagePath/svgPath/figmaUrl input and matching minArea/maxElements values so ids line up. It provides clear context and prerequisites but does not explicitly name when to prefer alternatives such as riv_import_svg or 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 at all, the description carries the full behavioral burden, and it does disclose useful traits: both inputs are forced to the same output size, the diff is thresholded, and the PNG color-codes differing (red) vs matching (dimmed) pixels. It says nothing about cost/runtime, what happens when the artboard or animation is missing in one file, or whether comparison failures error or return a partial result.

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, zero filler, with the operation and its conditions stated before the return values. Nothing is repeated from the schema and nothing is padding.

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?

Eleven parameters, no output schema, no annotations - the description compensates by spelling out the render conditions and the exact return payload (match rate, differing pixel count, diff PNG). The remaining gap is failure/edge behavior (mismatched artboards, unresolvable names) for a comparison tool whose whole value depends on the two inputs being comparable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: 'same artboard/animation/time' ties artboard, animation and time into one comparison contract, and 'forced to the same output size' explains that width/height govern both renders, not just one. That is a modest but genuine lift over the per-field schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb and resource: render two .riv files under identical conditions and compute a thresholded per-pixel diff, plus what it returns. The pixel-level framing implicitly separates it from riv_diff and riv_ab_compare, but no sibling is named, so an agent must infer the boundary.

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 is only implied by the mechanics described ("render the same artboard/animation/time from two .riv files"); there is no explicit when-to-use, when-not-to-use, or statement of how this differs from riv_diff / riv_ab_compare. Given those siblings exist, an agent gets no routing guidance.

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