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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description significantly adds behavioral context: it explains that the route sniffs bytes and rejects mismatched content types, it caps direct upload at 4MB and explains the 1.33x base64 inflation, it mentions the body limit, and it explicitly states that signInWithX tokens are single-use (nonces). This goes far beyond the annotation surface.

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 packs a lot of information into four sentences without being overly verbose. It front-loads the immediate purpose and return values, then provides usage alternatives and gotchas. It could be slightly tighter by removing redundant phrasing like 'the route sniffs the bytes and rejects a file whose content does not match the type you declared' which could be shortened to 'rejects if content mismatches declared type.' Almost no wasted words given the density.

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 4 parameters, good annotations, no output schema, and complex constraints (size limit, base64 inflation, single-use nonce, content validation), the description is nearly complete. It covers the return value shape, size constraints, alternative upload method, auth behavior, and acceptable formats. The only missing piece is explicit guidance on what error messages look like if the upload fails (e.g., size exceeded, content mismatch). Overall highly complete.

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 description coverage is 100% — all 4 parameters have descriptions. The tool description adds significant value: it clarifies the base64 format ('no data: URI prefix, no whitespace'), explains that altText is trimmed to 300 chars, and that contentType must match the actual bytes. It also gives a concrete example of how to use signInWithX (fresh, single-use, recipe from publish_essay). The only slight gap is no explicit list of accepted contentTypes beyond JPEG/PNG/GIF/WebP mentioned in the description.

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 explicitly states the core action: 'Upload an image and get back the stable `{ imageId, url }`'. It clearly specifies the verb (upload), the resource (image), and the return value. The purpose is distinct from sibling tools like update_profile or publish_essay by explaining how the output (`imageId`, `url`) is used with those other tools.

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 excellent when-to-use and when-not-to-use guidance. It explicitly tells the agent to use this tool for images under ~3MB and gives an alternative: 'for anything larger, POST the raw bytes to /api/images over plain HTTP'. It also warns that each signInWithX token is single-use, which prevents the agent from reusing stale credentials.

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