export_image

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

With no annotations provided, the description carries the full burden and does so well: it discloses the path sandbox and refusal behavior, that the working image is unchanged, that parent folders are auto-created, and that FITS keywords/astrometric solutions/view properties are preserved or dropped depending on format. These are non-obvious behavioral traits an agent needs.

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?

It is a dense single paragraph but every sentence carries load and the core action is front-loaded. Length is justified by the amount of genuinely useful constraint detail, though it could be split for readability.

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?

No output schema or annotations exist, and the description fully compensates by covering path rules, format-from-extension mapping, bit-depth defaults, metadata preservation, and non-mutation of the source image. Nothing an agent needs to call it correctly appears missing.

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 already 100%, so the baseline is 3, but the description adds real meaning: relative paths resolve under <workspace>/output, absolute paths must lie in output or the state folder, and bit-depth defaults per format map onto the 'bits' enum. It goes beyond restating the schema.

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 opens with a specific verb and resource: "Write an image to a file in the workspace's output or state folder," which clearly distinguishes it from read-only image tools and from preview siblings like save_preview. An agent can identify the core action without opening the schema.

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?

It gives detailed conditional rules for path resolution and format selection, which implicitly guides correct invocation, but it never states when to prefer this tool over alternatives such as save_preview or save_and_show_preview. Usage is implied rather than explicitly contrasted against siblings.

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