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

Annotations already declare the non-read-only, non-destructive, non-idempotent profile, so the bar is lower. The description adds real behavior beyond that: name conflicts never overwrite (which explains the non-idempotent/write semantics), and asset sources are copied without deleting the source.

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?

Four short sentences, each earning its place: the create action, the source requirement, the asset-copy behavior, and the conflict rule. Front-loaded with the core action.

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 write tool with no output schema and thin schema coverage, the description covers the source variants and the key mutation behaviors an agent needs. Remaining gaps — return value and how a name conflict is resolved (error vs. rename) — are minor.

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 only 20%, so the description must compensate, and it partially does — it clarifies that source is required for files, describes the three source forms (text, base64, asset), and that folders omit source. It says nothing about projectId or parentId, leaving those undocumented.

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?

States a specific verb+resource with scope ("Create a private document or folder in Files"), immediately distinguishing documents from folders. It does not name a sibling (e.g., update_file, upload_asset) to route against, so it stops short of 5.

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 conditional guidance about source types (documents require a source, folders do not) which is genuinely useful. However, it never says when to use this tool versus upload_asset, update_file, or find_assets — the sibling set that most overlaps with creation.

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