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

Annotations only mark readOnlyHint=false and destructiveHint=false, so the description carries the burden of behavioral disclosure. It adds substantial detail: the presigned URL is short-lived, uploads over 5MB are rejected, the team storage quota is checked up front, and the caller must send a matching Content-Type header. This fully explains side effects and constraints without contradicting 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 long, but every sentence carries load-bearing operational information and the structure is a clear numbered workflow with concrete examples. The key behavioral fact (returns a presigned URL, does not accept bytes) is front-loaded. It is not minimal, but the length is justified by the complexity of the two-step upload.

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 multi-step upload involving local temp files, compression, MIME constraints, size caps, quota checks, HTTP PUT semantics, and a follow-up finalization tool, this description is complete. It even includes cleanup and tells the agent exactly how to call the sibling next. Since an output schema exists, not describing return values in prose is acceptable.

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 100%, so the baseline is 3. The description adds operational meaning beyond the schema: fileSize is optional and refers to the file after compression, it is checked early against the 5MB cap and quota, and the authoritative size check happens in finalize_image_upload. It also clarifies that filename is for admin display and mimeType must match the uploaded Content-Type.

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?

States a specific verb+resource pair: prepares the first step of a two-step image upload and returns a presigned URL rather than accepting image bytes. Explicitly differentiates from finalize_image_upload by numbering itself Step 1 of 2, so an agent can distinguish it from the sibling without inspecting schemas.

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?

Provides an explicit numbered workflow covering pre-upload compression, when to call this tool, when to PUT to the returned URL, and when to call finalize_image_upload. It also states what the tool does NOT do (receive image bytes), which prevents an agent from attempting a direct upload through this conversation.

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