export_collection

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

The word 'Safely' hints that the export is non-destructive, which is useful. However, with no annotations provided, the description carries the full burden. It doesn't state whether the collection remains intact, what happens on write failure, whether the file overwrites existing exports, or the exact output file naming/location behavior.

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?

A single concise sentence, zero waste. However, it's arguably under-specified rather than efficiently concise — the 'Safely' prefix and 'configured directory' phrasing add mild tone but the sentence is appropriately short for a simple tool.

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 tool has one optional parameter, an output schema, and is a side-effecting operation. While simple, it could use more context: the acceptable format values, the meaning of 'configured directory', and confirmation about non-destructive behavior. It's adequate but leaves meaningful gaps for a tool that writes files.

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 single 'format' parameter (default 'json') is undocumented in the description. With 0% schema description coverage and no enums, the parameter only benefits from the default value in the schema. The description doesn't clarify acceptable values (e.g., 'json', 'csv'), case sensitivity, or invalid-format behavior. High penalty for having only 1 parameter yet still not describing it.

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?

Uses a specific verb ('export') and resource ('the local collection'), with clear output formats ('JSON or CSV') and destination ('configured directory'). It distinguishes itself from related collection tools like list_collection and value_collection, though it doesn't explicitly name them. It's clear but not maximally distinct from siblings since format choices are only implied, not enumerated.

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 implies this is for exporting data, distinct from listing or valuing the collection. However, it doesn't explain when to choose this over list_collection, whether it affects local state, or whether there are prerequisites (e.g., configured directory). No alternatives are named and no exclusions stated.

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