export.file

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

Annotations indicate destructiveHint=true, and the description reinforces this by noting 'Risk: gated' and requiring approval. It adds valuable context: a client cannot approve its own request, and it retries the same request id after user approval. It also mentions additional requirements (committed snapshot, approved output root). This goes beyond the annotations, which only say destructive, and clarifies the approval flow and retry mechanism. No contradiction.

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 a single paragraph, but it's dense and not front-loaded with the most critical info. It starts with the command name, then risk, then approval, then requirements. The approval and retry behavior are important but come after the risk. It's somewhat structured but could be broken into clearer sentences. No explicit summary of what the tool does is upfront.

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 tool's complexity (9 params, nested objects, destructive, gated), the description covers a lot: approval flow, retry, snapshot requirement, and session policy. However, it doesn't mention output schema or what the response looks like, but output schema exists, so that's okay. It also doesn't mention the `parameters` object specifics, but the schema's note about path extension hints. It seems complete enough for an agent to know the key operational constraints, though more detail on parameters could help.

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 schema description coverage is only 44%, so the description must compensate. It mentions `snapshotId` requirement and the need for a committed snapshot, but only touches on `path` and `snapshotId`. It doesn't explain the meaning of `parameters` object or the nested keys, but it notes that allowed keys depend on path extension, which is helpful. It also hints at `_transactionId` by mentioning session policy, but not explicitly. It adds some value beyond the schema but could do more for the 9 parameters.

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 command is `export.file` and implies it exports a file, but it doesn't explicitly say 'export a Blender file' or 'export scene to a file.' It mentions requirements and approval but the core action is only implied by the name. It distinguishes from siblings like `blender_export_extended` by being the basic export, but this is not explicitly stated. Overall clear, but slightly vague on the exact output.

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 mentions it's a 'gated' risk and requires local user approval, but doesn't explicitly state when to use this vs `blender_export_extended` or other alternatives. It says a client cannot approve its own request, which implies a two-party workflow, but no explicit 'use this when...' or 'instead of...' guidance. This is a gap for selection.

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