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

Beyond the annotations (non-readonly, non-idempotent), the description reveals key behavior: the URL is presigned, requires multipart form data with field name 'file', returns an attachment_id, and files persist only as long as the sandbox (~12 hours). It also notes the agent reads the file directly from its sandbox, adding important operational 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 tight sentences, each providing essential information: purpose, usage steps, and lifespan warning. No filler or repetition of schema details, making it efficient and front-loaded.

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

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

For a tool with no output schema, the description effectively explains what the tool returns (upload_url, attachment_id) and how to use those outputs in the follow-up message POST. It also covers timing, sandbox access, and persistence, making it complete for practical usage despite lacking explicit error handling details.

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

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

Schema coverage is 75%, with artifactId lacking a description. The description adds meaning by clarifying artifactId's role as the dashboard/message parent and explaining that the filename should correspond to a sandbox file. It also frames the params in the context of the upload-then-attach workflow, going beyond the schema's basic field names.

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: 'Issue a presigned upload URL for a file to attach to a Duvo Pulse dashboard message.' It provides specific examples ('an HTML dashboard to copy, or a screenshot to match'), which distinguishes it from sibling tools like generic createFileUploadUrl or createSandboxUploadUrl.

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 a clear usage workflow: POST file bytes to the returned upload_url, then pass attachment_id in the attachments array. It also advises to upload shortly before sending due to the 12-hour sandbox lifetime. It does not explicitly name alternative tools, but the context makes the intended use clear.

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