Decompile a .riv into an editable scene spec

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.