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

Annotations already mark readOnlyHint=true and destructiveHint=false, and the description adds substantial context around that: the tool never sees the image bytes, the returned URL is short-lived, uploads over 5MB are rejected, and the optional fileSize is checked up front against the 5MB cap and storage quota. It also exposes the subtle asymmetry that while this call itself is read-only, the overall workflow is a mutation performed via the direct PUT — which resolves any confusion the readOnlyHint could cause.

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 key concept ('Step 1 of 2... returns a presigned URL... does NOT receive image bytes') and the numbered workflow is clearly structured. It is a bit long and repeats the 5MB rule a couple of times, and the curl example is generous in detail, but every major section earns its place for a tool with a non-obvious two-step protocol.

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 a complex presigned-URL flow, the description is effectively a complete operating manual: preconditions (temp file, compression, allowed MIME), the exact invocation, the follow-up finalize call, and cleanup. An output schema exists and will specify return fields, so the description doesn't need to — the only marginal omission (what to do on a failed PUT status) is below the bar for an MCP-tool description.

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, and the description adds value beyond the schema: it clarifies fileSize should be the post-compression size ('the file you will actually upload, after any compression' is expanded by the compression step instructions), and it ties mimeType to the requirement that the PUT Header's Content-Type must match. It doesn't deeply enumerate each parameter, but with a fully documented schema that burden is already carried.

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 starts with a concrete, scoped purpose: 'Step 1 of 2 for adding an image (PNG / JPEG / GIF / WebP) to the current team media library.' It explicitly distinguishes its contract — it does NOT receive image bytes, it returns a presigned URL — and the sibling finalize_image_upload is directly named, so an agent immediately knows what this tool is and what it is not.

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 a complete procedural guide: compress/downscale any file >5MB first (with concrete sips/magick examples), call this tool with filename/mimeType/fileSize, HTTP PUT the file to the returned uploadUrl, then call finalize_image_upload, then delete the temp file. It also states hard applicability rules (5MB cap, four allowed MIME types) and explicitly names the required follow-up sibling, so an agent knows exactly when and how to use it.

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