upload_assets

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

Annotations already declare destructiveHint=true, so the description does not need to restate that basic safety posture. It adds a concrete 512 MiB per-file limit and discloses that the result separates succeeded and failed entries, giving useful behavioral context beyond the annotations.

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?

Two sentences carry the full core message with no filler. The primary action is front-loaded, and each added clause earns its place by covering replacement, limits, and result behavior.

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?

Given the destructive annotation and the complex nested assets schema, the description covers the main behaviors but leaves operational gaps: how replacement items should be structured relative to the required path/type fields, and what 'designated project' means in practice. With no output schema, the partial-success mention helps but is not a full contract.

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 top-level assets parameter has no schema description, but the description does add meaning by explaining new-upload versus replace-by-id behavior and by mentioning file-size limits and result partitioning. It does not explain how the required path and type fields interact with replacement items, though the nested schema descriptions partially compensate.

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 verb and resource: uploading local files into the project, plus a second replacement mode keyed by asset id. This makes the core purpose clear, but it does not explicitly distinguish the replacement mode from sibling tools like replace_asset or create_assets, so some differentiation effort remains.

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 two modes imply when to use the tool: upload new local files or replace an existing asset source by id. However, it never names alternatives such as create_assets or replace_asset, nor does it say when not to use those tools, so usage guidance is implicit rather than explicit.

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