open_in_darktable

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

With no annotations, the description carries the full burden, and it delivers meaningful behavior: first-launch film roll registration, automatic XMP sidecar pickup, and filter application via a named Lua API. It does not disclose whether the GUI launch blocks until exit or what happens if the darktable executable is missing, but it covers the most important side effects.

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 main purpose and side effects are front-loaded, followed by a compact specification of every supported rating form. The text is dense but each clause contributes; only the internal Lua API reference is mildly incidental to actual invocation, and the overall length is justified by the complexity of the filtering behavior.

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 5-parameter, no-output-schema tool with no annotations, the description covers the purpose, the non-obvious rating filter combinations, and key side effects. It does not discuss the darktable_path parameter or process return behavior, but those are low-stakes: darktable_path has a schema default, and a GUI launcher does not require detailed return documentation.

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 100%, so the baseline is 3, but the description adds real value by explaining how the rating parameters combine: exact rating=N, rating_min=N, rating_max=N, arbitrary inner ranges, or no filter. This gives the agent semantic guidance beyond the individual integer descriptions in 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 states a specific verb ('Launch'), a clear resource ('the darktable GUI on a folder'), and the distinguishing behavior: it is the tool that opens an interactive GUI rather than performing batch operations like export_images or apply_preset. It also differentiates itself by naming the exact outcome: film roll registration and an already-filtered lighttable.

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 context is clear: use this when the user wants to open the interactive darktable GUI on a folder, optionally with rating filters. It does not explicitly name or contrast with sibling tools such as view_photos or rate_photos, so it stops short of a 5, but the launch-GUI framing makes the intended usage obvious.

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