Skip to main content
Glama
Sign In

gaisho

by co.gaisho
OverviewDiscussionsAdmin

search_products

Read-only

Find products from the shopper's needs or keywords. Returns the match count, up to 15 candidates and the interpreted conditions. Full matches come first; soft preferences affect ranking rather than filtering. The interpreted conditions show alternatives joined with or (shared requirements apply to each), preferences that only rank, and an Ignored line for requirements no listed spec expresses; those were not used as filters. Ranking also considers request fit, ratings weighted by review count and brand diversity; the result states the applied order. Explicit requests to sort by most reviewed or highest rated are supported. When more match than are listed, "refine" gives facts for narrowing: price range and, for each key spec not yet stated, its values with how common each is and its median price. Each product shows its representative offer (offer id) at its stored price after coupons, its unit price and where that sits among products with the same key specs, its seller (with the seller's vetting risk when medium or high) and its image link; these stored prices support candidate comparison and do not establish a current offer quote. A link, ASIN, GTIN or model number matches that one product.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "search_products"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryYesConcise product needs: product type, required features, explicit size or quantity bounds, hard exclusions, and any stated USD budget. Include only requirements actually given by the shopper; preserve exact values, ranges and comparison directions. State alternatives or options to compare in one query with "or" (e.g. "non-dimmable, dimmable or color-adjustable"); requirements they share apply to every alternative. Mark soft preferences as preferred; everything not marked preferred is required. Leave answer-format, research-process and fact-reporting requests without target values out of query; retain them for detail checks and the answer.
filtersNoOptional: {"price_max": 100} or attribute keys from `get_category_overview`, not display names. Unknown keys fail explicitly. Filters require a needs-based query for an indexed product type, not an identifier lookup.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A3.9/5.0
Behavior5/5

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

Annotations only declare a safe read, but the description goes far beyond: match count, a 15-candidate cap, soft preferences that rank rather than filter, an Ignored line for unmatched requirements, ranking factors (request fit, review-weighted ratings, brand diversity), and the caveat that stored prices are not current offer quotes. Seller vetting risk, coupon-adjusted pricing, and unit-price context are all disclosed, which is exactly the behavioral detail annotations cannot carry.

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?

It is front-loaded with the purpose, which is good, but it then delivers a dense wall of text mixing return format, ranking internals, refinement behavior, and per-product field listings. Every clause is informative, yet the lack of structure (sentences/lists) makes it hard to scan for the one or two facts an agent needs at call time.

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

Completeness5/5

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

There is no output schema, so the description carries the full burden of explaining returns, and it does: match count, candidate cap, interpreted conditions, per-product offer/seller/image fields, and the refine payload. For a tool of this complexity with nested filter objects, nothing an agent needs to call it correctly appears to be missing.

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 the query and filters semantics are already documented in full. The description does add one genuinely new constraint — filters require a needs-based query for an indexed product type, not an identifier lookup, and unknown keys fail explicitly — but the rest restates how query should be formed. Baseline 3 is appropriate when the schema does the heavy lifting.

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

Purpose4/5

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

States a specific verb and resource: 'Find products from the shopper's needs or keywords,' and adds that an identifier matches a single product. It is clearly distinguishable in substance from siblings like find_deals or search_products_by_image, but it never names those siblings, so the differentiation is implicit rather than explicit.

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

Usage Guidelines3/5

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

Gives concrete context for use: needs/keyword queries, explicit sort-by-review or sort-by-rating requests, and the 'refine' path when matches exceed the listed 15. However, it never routes the agent away from this tool toward alternatives such as get_product for ID lookups or find_deals for deals, leaving the when-not-to-use case unstated.

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