register_creative_asset

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

Annotations already convey that the operation is not read-only, is destructive, and is not idempotent. The description adds a meaningful extra behavioral fact: Raven stores metadata and a URI/path, not the actual file bytes. It does not elaborate on destructive side effects, but that risk is already exposed by the annotations.

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

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

The description is two focused sentences. The core action is front-loaded, and the meaningful caveat about storing metadata instead of bytes is expressed economically. There is no filler or redundant restating of the tool name.

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 six parameters, a nested metadata object, and no output schema, the description covers purpose and storage semantics well but does not explain what the operation returns or what a successful registration causally changes. Since there is no output schema to rely on, that is a significant 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 description coverage is 100%, so every parameter, including required `uri` and `type`, is already documented structureally. The description reinforces 'uri/path' and 'local or remote' but does not add meaning beyond what the schema already provides, so the baseline score 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 identifies the action (register), resource (creative asset), and intended context (Raven jobs), and even explains the key distinction from upload: only metadata and a URI/path are stored, not file bytes. It does not explicitly differentiate against the large sibling tool list by name, so it falls just short of maximum clarity.

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 'local-first analog of upload' sentence gives the agent a practical usage signal: choose this when the asset should be represented by metadata and a URI/path rather than uploaded bytes. It does not explicitly spell out when to use upload instead or name sibling tools as alternatives, but the context is clear enough to guide basic selection.

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