Search photos by example image

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 reveals important traits: the tool accepts an image in three ways, requires care with image_base64 (chat assistants cannot produce it from a seen image), and that results carry an attribution that must be shown. It also transparently explains the fallback behavior when no image can be sent. This goes well beyond just stating the function.

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 highly structured and information-dense. It front-loads the primary purpose and use case, then organizes the input methods as a numbered list, and includes crucial warnings. Every sentence adds necessary context—no fluff. The length is justified by the tool's complexity and the need to prevent common misuse (e.g., fabricating base64).

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?

The description provides rich context for the main workflow: how to supply the reference image, how to tweak with text, what to do if the image cannot be forwarded, and a note about attribution in results. However, it does not describe the full result structure (beyond attribution) or explain the optional filter parameters, which might be relevant in some use cases. Given no output schema and 12 optional parameters, a bit more detail about expected results and the remaining filters would elevate completeness to excellent.

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 zero descriptions for its 12 parameters, so the description must compensate. It explicitly explains the semantics of the most critical parameters: image_url, image_file, image_base64, q, and text_alpha, including practical examples and constraints. However, it leaves cursor, source, after_date, color_name, orientation, license_type, and photographer undocumented. While these are likely less central, they remain ambiguous; the description covers the core parameter decisions but not all of them.

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 tool's purpose with a specific verb ('Find') and resource ('visually similar stock photos from an EXAMPLE IMAGE'). It also provides example use cases ('like this but with their hands raised') and distinguishes itself from the sibling tool search_photos by emphasizing the image-based similarity search. The phrase 'This is the right tool for...' further clarifies its specific niche.

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 explicitly states when to use this tool ('find photos LIKE THIS but <change>') and provides clear alternatives: if the reference image cannot be sent, use search_photos. It also gives detailed guidance on the three ways to provide the reference image (image_url, image_file, image_base64), including warnings about which methods are appropriate for chat assistants vs. programmatic clients. This is comprehensive usage guidance with exclusions and alternatives.

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