Upload Asset

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

The description discloses a nontrivial side effect: 'WebP re-encode strips EXIF/AI metadata' – something not present in annotations. It also mentions the cost ($0.15) and API key requirement, which are operationally important. Annotations only indicate readOnlyHint=false and destructiveHint=false, so the description adds significant behavioral context without contradicting 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 three sentences, front-loads the core function, and efficiently includes usage recipe, alternatives, and cost/auth. It's appropriately sized for the tool's complexity, though it could be slightly more structured with the use-case as a separate sentence for even better scannability.

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 13 parameters, low schema coverage, and an output schema, the description provides a concrete, actionable recipe for the most common scenario (inventory photos), mentions the return value (asset_id), and notes cost/auth. However, it doesn't cover other potential uses (e.g., uploading documents or receipts directly), nor does it explain the purpose of several less-common parameters. The tool's complexity warrants a more thorough description to be fully complete.

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

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

Schema description coverage is only 38% with 13 parameters, so the description must compensate. While it highlights the key parameters for the inventory workflow (entity_type, entity_id, role, image_base64), it omits explanations for url, filename, metadata, mime_type, asset_type, parent_asset_id, etc. The single use-case recipe doesn't cover the full parameter space, leaving many parameters semantically undefined.

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 'Upload image bytes to Dayze storage' – a specific verb and resource. It also distinguishes the tool by noting the WebP re-encode behavior and returning asset_id, separating it from siblings like attach_asset and upload_photo. The concrete inventory use-case further clarifies the intended 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?

It offers explicit guidance for the primary use case (inventory photos with entity_type=inventory, entity_id, role=photo, image_base64) and suggests an alternative workflow ('Or upload then attach_asset'). However, it doesn't explicitly state when not to use this tool (e.g., if the caller has a URL instead of bytes, or if an upload_photo is more appropriate), leaving some 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.