presign_task_attachments

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

Discloses batch operation, per-file size limit, blocked MIME types, return format (attachment_id, put_url, expires_at), and error response (400). No annotations exist, so description carries full burden; it provides substantial behavioral context.

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 sentences, purpose is front-loaded. Each sentence adds unique value: purpose, parameter details, constraints, and follow-up action. No redundancy or unnecessary 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?

Covers the full workflow: presign URLs, caller PUTs, then commit. Includes constraints, return fields, and error handling. With an output schema present, no further details needed. Complete for a 2-parameter 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 has 0% description coverage but description explains task_id accepts multiple reference forms (UUID, shorthand, etc.) and resolves to UUID. For files, specifies it's a list of {filename, content_type, size_bytes} and notes wire key alignment. Adds critical meaning 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?

Description clearly states 'Batch-presign S3 PUT URLs for files to attach to a task.' It specifies the action (presign) and resource (files for tasks), distinguishing it from siblings like commit_task_attachments.

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?

Instructs that after presigning, the caller must PUT blobs before invoking commit_task_attachments. Mentions alternative reference forms for task_id and constraints (25 MB cap, blocked MIME). Does not explicitly state when not to use, but the sequential usage is clear.

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