Skip to main content
Glama
Sign In

gaisho

by co.gaisho
OverviewDiscussionsAdmin

search_products_by_image

Identify a pictured product in the catalog and find similar products. Stores submitted images and their identification and matching results for 30 days so they can be queried again by image_id. Give one picture: image_url (a public link the server downloads), image_data_url (data:image/jpeg;base64,...; JPEG, PNG, GIF or WebP, at most 5 MB) or image_id (the id of a picture searched before, kept 30 days, to look at another item in it without uploading again). A phone photo, a product image, or a screenshot of a page or of a shopping assistant's answer all work. Returns id (the picture's id), objects (every item read in the picture: label, brand, product, model, variant, barcode, text on the pack, search terms), object (the item searched) and items: products of the catalog (product_id for get_product, title, brand, image, the price and link of its main offer), in tiers: same = this item, maybe, size = another pack size, substitute, variant = another item of the same line, unjudged = not checked; p_same = the probability it is this item; same_image = the listing's own image is the picture. counts: products per tier, different (unrelated, not listed) included. message says why there are no items. errors lists the parts that failed (the answer is then partial). The first search of a picture takes several seconds (reading it and checking candidates); the same picture again is cached.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search_products_by_image"
  }
}

Input Schema

NameRequiredDescriptionDefault
verifyNoCheck the top 30 candidates against the picture (a few seconds more; checked ones are cached). false = unchecked candidates only (tier unjudged), fastest.
image_idNoThe id returned for a picture searched before: look at another item in it without uploading again.
image_urlNoA picture link the server downloads. Give one of image_url, image_data_url or image_id.
object_indexNoWhich item in the picture (from 0; 0 = the most prominent; all items read are in the returned objects).
image_data_urlNoThe picture as a data URL (data:image/jpeg;base64,...; JPEG, PNG, GIF or WebP, at most 5 MB), for a local picture.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4/5.0
Behavior4/5

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

Annotations declare readOnlyHint=false and idempotentHint=false, so the description adds real value by explaining why: images and results are stored for 30 days and are re-queryable by image_id. It also discloses latency (first search takes several seconds, repeats are cached) and that 'errors lists the parts that failed (the answer is then partial)', so a degradation path is signalled. It stops short of stating any auth or quota constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded, but the body is a dense run of long parenthetical sentences: the exhaustive tier list and the return-field enumeration read as a data dictionary rather than a summary. Most sentences do earn their place, but the structure could be split into shorter, scannable statements.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the full burden of the return shape, and it does so thoroughly: id, objects, object, items with tier semantics, p_same, same_image, counts, message, and errors. For a high-complexity, open-world identification tool, that is nearly complete; only authentication and failure-mode behaviour beyond the partial-errors note are unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all five parameters are already documented in the schema, including verify (top-30 candidate check) and object_index (which item in the picture). The description mirrors the image_source parameter meanings and adds the store-and-reuse rationale for image_id, but it says nothing about verify or object_index beyond what the schema states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Identify a pictured product in the catalog and find similar products.' This is clearly distinct from the sibling text-search tools (search_products, show_products) and from get_product, which the description references by name for product_id follow-up.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete when-to-use guidance for each input mode: image_url for a public link, image_data_url for a local picture, image_id to re-examine a stored picture without re-uploading. It also clarifies acceptable inputs (phone photo, product image, screenshot) and when to set verify=false for speed, but it never explicitly says to prefer a sibling text-search tool when no picture exists.

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

All gaisho toolsInspect
Try in Browser
Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources