lightroom_search_photos

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It does not state whether the operation is read-only, what happens if multiple criteria are combined, or the effect of the 'limit' parameter. It also does not mention any side effects or prerequisites. This minimal disclosure is insufficient for a search tool with no annotation safety net.

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 a single, tightly packed sentence that front-loads the action and enumerates all key criteria without redundancy. Every word earns its place, and it is easily scannable. This is exemplary conciseness.

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 search tool with 5 parameters and an output schema, the description covers the core search semantics but misses the 'limit' parameter's behavior and any guidance on combining filters. It also does not address the existence of a similarly named sibling tool, leaving ambiguity. It is adequate for basic use but incomplete for nuanced invocation.

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 0%, so the description must compensate. It maps four of the five parameters to human-readable concepts: text→query, star rating→rating, pick flag→flag, color label→color_label. However, it omits the 'limit' parameter and provides no details on allowed values or formats. This partial coverage earns a 3, above the low baseline but not fully compensating for the schema gap.

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 ('search') and resource ('photos in Lightroom Classic'), and enumerates the search criteria (text, star rating, pick flag, color label). It is clear and unambiguous, though it does not explicitly differentiate from the sibling 'search_photos' tool, which could be a generic alternative. Thus it earns a 4 rather than 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 no guidance on when to use this tool versus alternatives like 'search_photos' or 'get_selected_photos'. It only states what it does, with no context for selection, no exclusions, and no mention of scenarios where another tool would be preferred. This is a clear gap.

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