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

Discloses that the operation applies a style to multiple photos and returns applied/missed counts, implying a batch mutation. No annotations exist, so it carries more burden; however, it does not state side effects like whether an existing style is overwritten, but the return counts provide useful behavioral context.

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 sentences, front-loaded with the action, and includes necessary operational preconditions. Slightly more than minimal but each sentence adds value; no fluff.

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?

Covers what it does, the exact-match source, required runtime, and return counts. With no annotations and no output schema, this is reasonably complete for a batch operation, though it doesn't mention error cases or whether partial failures occur; still adequate.

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 100% and the description reinforces the exact-match constraint already in the schema. It adds nuance that preset_name must match a style name from list_styles, clarifying the enum-like source beyond the schema, which benefits selection.

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?

States a specific verb (apply), the resource (darktable style/preset), the target (one or more photos) and the requ�rement of an exact style name, distinguishing it from sibling import/export/rate tools.

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?

Explicitly requires the preset_name to come from list_styles and notes darktable must be running with the plugin, giving clear preconditions. It does not enumerate when-not-to-use, but the exact-match instruction and mention of list_styles effectively routes the agent to the correct sibling tool.

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

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

With no annotations provided, the description fully carries the behavioral disclosure burden. It explains sidecar placement, darktable auto-import, the audit log, the 'never replace existing sidecar' behavior, and the error handling for unrecognizable sidecars. It also highlights the destructive force option via the schema.

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 front-loaded with the core action and efficiently conveys side effects, error behavior, and integration details in five concise sentences. No sentence is redundant or filler.

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 no output schema and no annotations, the description covers the essential invocation context: file locations, side effects, rating semantics, audit logging, and safety behavior. It does not explicitly describe the function's return value or success/failure response, but the described side effects make the tool's behavior highly predictable.

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 input schema already describes all four parameters with 100% coverage. The description adds value by explaining the rating scale semantics (-1 reject, 0 unrated, 1-5 stars), sidecar naming, and the purpose of the ratings.jsonl log, going beyond the schema's basic type and range constraints.

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 a specific action ('Write XMP sidecars') on a specific resource ('a batch of {stem: rating} pairs'). It makes the tool's purpose unambiguous, though it does not explicitly differentiate it from the sibling rate_photos tool by name.

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 tool is for batch-rating operations by writing XMP sidecars that darktable picks up automatically. However, it does not explicitly state when to prefer this over siblings like rate_photos, or when not to use it.

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

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.

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it discloses EXIF-based auto-rotation, resizing to max_dim and thumb_dim, recursive scanning, mirrored output tree, handling of duplicate filenames, and the instruction not to assume output paths. This gives the agent a reliable mental model of what will happen.

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 several sentences long but each sentence adds a useful detail about behavior, output, or path resolution. It is front-loaded with the core purpose and avoids filler, though it slightly repeats default values already present in the schema.

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 no annotations and no output schema, the description covers the essential return information: a list of items with preview paths and per-file EXIF summaries. It could be more explicit about the exact output item field names or error conditions, but an agent has enough context to invoke the tool and consume its results correctly.

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 100%, so the schema already documents every parameter. The description adds some operational context, such as thumbnails being 'for token-efficient first-pass culling' and the mirroring behavior, but it does not materially enrich parameter semantics beyond what the schema provides.

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 action on a specific resource: 'Extract auto-rotated JPEG previews from a directory of raw files'. It also clarifies the downstream purpose ('for vision-based rating') and distinguishes itself from siblings like view_photos, rate_photos, and export_images by focusing on preview generation rather than viewing, rating, or exporting.

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 gives clear context for when to use the tool: when raw files need upright JPEG previews for rating workflows. It does not explicitly name alternatives or state when not to use this tool, but the use case is specific enough that an agent can infer appropriate selection among the listed siblings.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds meaningful context: the tool returns the count of newly-imported photos, and requires darktable to be running with the darktable-mcp Lua plugin installed. However, it does not disclose side effects such as how existing film rolls or duplicates are handled, or whether files are referenced in place or copied.

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?

Four sentences, tightly packed and front-loaded with the core purpose before usage context, return value, and prerequisite. Every sentence earns its place; there is no redundancy or filler.

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 2-parameter tool with a fully documented schema and no output schema, the description covers the essentials: purpose, when to use it, the return value (count), and a key prerequisite (running darktable with the Lua plugin). Minor gaps like duplicate handling and explicit side effects keep it from a 5.

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 schema already documents both parameters (source_path, recursive) with descriptions and defaults. The description reinforces the path semantics ('folder of photos') but adds no new parameter-level detail. Baseline 3 is appropriate.

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+resource: 'Register a folder as a film roll in the user's darktable library.' This clearly identifies what the tool does and distinguishes it from the sibling import_from_camera by specifying a local-folder source ('copied photos from a card or external drive') rather than camera import.

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 gives a clear when-to-use scenario: 'Useful when you've copied photos from a card or external drive and want darktable to know about them.' It does not explicitly name alternatives or provide exclusions, but the stated context is sufficient for an agent to select this tool over import_from_camera in most cases.

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

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

With no annotations provided, the description carries the full burden, and it does so thoroughly: it explains libgphoto2 detection, non-overwriting collision behavior, filename/subdirectory conventions, serial-number edge cases, timeout/resume semantics, and observable progress via .import.log. These are genuine behavioral disclosures beyond what a schema could infer.

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 long but information-dense, with the primary use condition front-loaded and every sentence serving a distinct purpose. Slight structural awkwardness in the later edge-case sentences and an embedded user directive ('Import the destination recursively.') keep it from a perfect score.

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 no output schema and meaningful side effects, the description is remarkably complete: it states the return value, the follow-up workflow, collision handling, timeout behavior, progress observability, and naming rationale. An agent has enough context to invoke it correctly and debug its behavior.

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 100%, so all three parameters are already documented in the input schema. The description adds some operational context around destination subdirectories and timeout recovery, but it does not materially extend parameter meaning beyond what the schema already provides.

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 names a specific action ('copies all photos to a local directory'), identifies the physical-camera context, and explicitly separates this from the library-registration step performed by import_batch. The tool's scope is unambiguous and clearly distinguished from its siblings.

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 opens with the exact condition for use ('Use when a camera or memory card is physically connected') and explicitly instructs to follow up with import_batch on the returned destination path. This provides both when-to-use and when-not-to-stop guidance, with the alternative tool named directly.

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

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

With no annotations available, the description carries the burden and discloses the key behavioral context: it returns only name/description per style and requires darktable to be running with the darktable-mcp Lua plugin installed. It doesn't detail error cases or explicitly state read-only behavior, but 'list' plus the return description makes the non-destructive nature reasonably clear.

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?

Four short sentences, each earning its place: the action, the return content, the prerequisite relationship to apply_preset, and the runtime requirement. The most important information is front-loaded and there is no filler.

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 zero-parameter listing tool with no output schema, the description covers the purpose, the returned data shape, the dependency on apply_preset, and the external runtime prerequisite. Nothing essential for invoking it correctly is 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?

The input schema has no parameters, so there is nothing for the description to add about parameters. The 0-parameter baseline of 4 applies; the description instead usefully explains what the output contains.

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: 'List all darktable styles (presets) installed on the user's system.' It also states the returned fields (name and description), which makes the tool's function unambiguous and distinct from sibling tools like apply_preset.

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 explicitly states when this tool is required: 'Required discovery step before calling apply_preset, since style names must match exactly.' This provides clear sequencing and identifies the relevant sibling, so an agent knows to call this before apply_preset and why.

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

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.

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It reveals only the runtime prerequisite and does not state whether an existing rating is overwritten, whether the operation is reversible, what happens if darktable is not running, or error behavior. For a mutation tool with zero annotation coverage, this is a significant gap.

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?

Two sentences with zero waste. The action is front-loaded, and the prerequisite sentence earns its place by warning the agent about a hard runtime requirement. Nothing redundant or extraneous.

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 simple 2-parameter tool with fully documented schema, the description covers the core action and the critical prerequisite. However, it lacks differentiation from the near-duplicate sibling 'apply_ratings_batch', and with no annotations or output schema, a bit more behavioral context would make it fully self-sufficient.

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 100%, with both 'photo_ids' and 'rating' fully documented in the input schema (including the rating scale -1/0/1-5). The description adds no meaningful parameter meaning beyond the schema, so the baseline of 3 applies.

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 and resource: 'Apply a star rating to one or more photos in the user's darktable library.' This is clear and unambiguous. However, it does not distinguish itself from the sibling tool 'apply_ratings_batch', which appears to perform a nearly identical operation, so it misses the sibling-differentiation mark for a 5.

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 provides a runtime prerequisite (darktable running with the darktable-mcp Lua plugin installed) but gives no guidance on when to use this tool versus alternatives like 'apply_ratings_batch'. There is no mention of exclusions, precedence, or which tool fits a given scenario, so an agent gets no tool-selection help.

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

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

With no annotations, the description carries the behavioral burden. It discloses the exact return fields, the fact that the returned path is directly usable by export_images, and the runtime prerequisite. It does not mention sorting, pagination, or read-only guarantees, but those are minor for a simple browse operation.

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 sentences, front-loaded with purpose, a useful integration note, and the prerequisite. No filler.

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 no output schema, the description compensates by listing return fields. It also states the necessary runtime prerequisite and the relationship to export_images. The only omissions are minor behavioral details like sort order and error behavior when the plugin is absent.

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 description need only add value over the schema. It adds the fact that filter and rating_min can be combined ('or both'), but otherwise restates the schema's descriptions. This is a slight but not substantial addition.

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 ('Browse photos in the user's darktable library'), names the core filtering capabilities, and states the returned fields. This clearly separates it from siblings like rate_photos, import_batch, or export_images, and even points downstream to export_images.

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 states the operation context (browsing/filtering before export) and the requirement that darktable be running with the plugin installed. It does not explicitly enumerate alternatives or when-not-to-use, but the export_images reference and filter description give clear usage context.

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