export_images

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

With no annotations provided, the description carries full behavioral disclosure. It reveals that output filenames are de-collided to avoid overwrites, that the actual written file may not match the expected stem, and that the real path must be read from the .export_images.jsonl side file. This materially changes how an agent should invoke and inspect results.

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?

Three dense sentences with no filler. The purpose is front-loaded, and each sentence adds necessary operational detail—input format expectations, name-collision behavior, and how to recover the real output path. The side-file sentence is long but justified.

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 tool with six parameters, no annotations, and no output schema, the description covers the key workflow: inputs from view_photos, output naming hazards, and the side file to read. The main gaps are the exact semantics of output_path (directory vs file prefix) and when the side file is produced, but the description is largely complete for successful use.

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 description coverage is 50%, and the description compensates for the undocumented output_path by explaining de-collision and the side file's output field. It also adds meaning to photo_ids by linking directly to view_photos.path. It does not clarify whether output_path is a directory or base filename, and format/quality semantics are only lightly implied.

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 action ('Export photos'), the output formats (JPEG/PNG/TIFF), and the mechanism ('via darktable-cli'). This distinguishes it from siblings like view_photos or extract_previews, so an agent can identify what this tool does without needing to inspect 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 concrete usage context: pass the path field from view_photos directly into photo_ids, and use this tool when exporting photos to the listed formats. It does not explicitly name sibling alternatives or say 'do not use X', but the integration instruction provides enough context for correct selection.

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