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

Beyond annotations (readOnlyHint false, destructiveHint false), the description discloses deduplication behavior and the two possible response scenarios. It also notes the ChangeRequest write mechanism and includes a security reminder to treat stored content as data, not instructions. These add valuable 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?

The description starts with the core purpose, then the endpoint, then multi-space guidance, and ends with a general ChangeRequest/security note. It is reasonably concise, but the final security reminder is somewhat tangential and could be omitted without losing essential usage info.

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?

The description covers both response scenarios (presigned URL or dedup with public URL and asset id) and the multi-space flow. Since there is no output schema, this is important. It does not detail all optional parameters, but the essential information needed to call the tool correctly is present.

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 description adds meaning for targetSpaceId via the auth_verify flow and implies contentHash usage through the deduplication note. With only 25% schema description coverage, it doesn't fully explain parameters like fileName, mimeType, sizeBytes, context, or playbook, though these are fairly self-explanatory. It partially compensates but leaves gaps.

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 requests a presigned (or dev) upload URL for an asset and mentions the deduplication behavior (returning public URL and asset id if bytes already exist). It distinguishes from sibling assets_create_text_upload_url by focusing on binary bytes, though it doesn't explicitly name the sibling.

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 concrete guidance for multi-space accounts: call auth_verify, ask the user which space to use, and pass targetSpaceId. Also notes that writes go through ChangeRequests. However, it does not explicitly compare with alternatives like assets_create_text_upload_url, leaving the selection decision partly implicit.

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