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

Annotations only indicate non-readOnly, non-idempotent, and non-destructive—minimal safety info. The description significantly enriches this by disclosing short-lived expiry, one-time token consumption, that the attachment is created only after successful upload, and that it won't appear in list_taskattachments until then. These behavioral details go far beyond annotations, aiding correct usage and expectation management.

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 front-loaded with the core purpose, then explains the required upload flow and important caveats. Though multi-sentence (actually one long compound sentence), it contains no fluff; each clause adds essential information about usage, behavior, and constraints. It is concise relative to the complexity of the operation.

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 the one parameter, no output schema, and non-trivial multi-step nature, the description covers all critical aspects: how to obtain the URL, how to upload (multipart, field name), expiry, token one-time use, attachment creation timing, and relation to list_task_attachments. It is fully self-contained and sufficient for correct invocation without additional oracle calls.

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 a clear description for task_id: 'ID of the task the file will be attached to.' The description adds little beyond saying the attachment is 'scoped to task_id', which slightly reinforces but does not materially extend semantics. Since the schema covers the only parameter adequately, a baseline of 3 is appropriate; the description does not need to compensate for missing schema documentation.

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 purpose: obtaining a short-lived, one-time URL to upload file bytes for attachment to a task. It explicitly distinguishes itself from other tools by emphasizing it is 'the only way to attach a file to a task over MCP' since task attachments lack inline-content creation. This specific verb+resource description effectively differentiates it from siblings like request_attachment_upload.

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 provides explicit when-to-use guidance by stating it's the sole method for task attachments and correct use is the only way. It also details the required steps (POST multipart form data with field 'file' before expiry) and clarifies that the call merely reserves a slot and does not create the attachment until the upload completes. This effectively tells the agent when and how to invoke the tool versus alternatives.

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