upload-file-content

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

Annotations flag destructiveHint=true and readOnlyHint=false, and the description adds specific behavioral details: 'Overwrites existing files without warning' and the risk of truncation with no error. It also discloses the 250MB limit and that the body travels as a tool argument. This goes beyond the annotations and gives the agent actionable warnings.

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 compact but structurally scattered. It starts with an ambiguous sentence, then jumps into a tip block, then the overwrite warning. It's not front-loaded with a clear purpose statement, and the information is presented as a series of caveats rather than a coherent explanation. It is still concise, but the organization could be improved.

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 key operational risks (truncation, overwrite, size) and points to the alternative for large files. However, it does not explicitly state the tool's primary function or return value, and it omits any prerequisites (e.g., authentication, permissions). Given no output schema, the agent must infer the purpose from the title and the scattered hints, which introduces ambiguity.

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 baseline is 3. The description adds meaningful context that is not in the schema: the truncation risk when the base64 string is cut off, the size limit, and the path format for new files. This enriches the understanding of the body and driveItemId parameters beyond their schema descriptions.

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 never explicitly states 'This tool uploads file content to a specified drive item.' It opens with an ambiguous fragment, 'The content stream, if the item represents a file,' and then provides operational tips. The purpose is inferable from the title and the tip about path format, but the description itself lacks a clear verb+resource statement.

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 explicit guidance on when to avoid this tool: it warns against using it for large files and directs the agent to create-upload-session instead. It also notes that new files use a path format, which differentiates from existing items. It does not explicitly state when to use this tool over alternatives, but the exclusion is clear.

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