Start an upload

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

Beyond the annotations, the description reveals that the call returns versionId for use as upload_id and that incomplete uploads expire after six hours. It conveys that this is a preparation step rather than the transfer itself, though it does not fully spell out the side effect of creating a pending upload session.

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?

Every sentence has a distinct job: trigger condition, return-value contract, slug guidance, byte-handling warning, connection check, and expiration. There is no filler or repetition.

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 workflow with no output schema, the description covers the essential invocation path: start the upload, get versionId, use it in upload_write, then publish/update. It also handles edge cases like slug omission, expiration, and connection limits, making it complete enough for correct invocation.

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%, so the baseline is 3. The description reinforces slug's omit/include behavior and says including it means whole-content replacement, but it does not add much about title, tenant_id, share_token, or operation_key beyond what the schema already documents.

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 names a specific action and resource: preparing a large document or multi-file website for remote publication. It explicitly distinguishes this from inline publish/update and from upload_write, so an agent can identify when this tool starts an upload versus when it sends bytes.

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?

It gives an explicit trigger condition: use this when inline publish/update would exceed the 2 MiB MCP request limit. It also tells the agent to send bytes via upload_write, never a local path, and to check connection for deployment limits, which routes the agent to the correct siblings.

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