Skip to main content
Glama

search_products

Read-onlyIdempotent

Search the shop catalogue. Give words (query), a category, a maximum price in cents or only products in stock. Returns up to 8 products (id, name, price_formatted, available, summary, options such as colour or size) and answer_kind: exact (they match), relaxed or related (NOT exact: only the closest, say so), shop (a question about the shop, see shop_answer) or none (nothing matches: say so, never offer unrelated products).

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"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoHow many products to return, from 1 to 8
queryNoWhat to look for: the customer's words or, for a vague need, a product type or synonym of your own that fits
session_idNoOnly if your client does not keep the MCP session (the Mcp-Session-Id header): the session_id that an earlier answer of this server gave you. It keeps the same cart between calls.
category_idNoOnly products of this category (see list_categories)
in_stock_onlyNotrue: only products that can be bought now
max_price_centsNoMaximum price in cents: 5000 means 50.00

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedInput schema / properties / in_stock_only / description
      Added value: +"true: only products that can be bought now"
    • addedInput schema / properties / limit / description
      Added value: +"How many products to return, from 1 to 8"
  2. First observed

TDQS

A4.4/5.0
Behavior5/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds substantive context the annotations cannot convey: the result cap of 8, the returned fields (id, name, price_formatted, available, summary, options) in the absence of an output schema, and the answer_kind taxonomy that governs whether the agent should present results as exact or disclaim near matches.

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

Conciseness4/5

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

Two sentences, front-loaded with purpose before the filter list and the return/answer_kind contract. The parenthetical enumerations make the second sentence dense to parse, but no sentence is filler and the critical 'never offer unrelated products' warning lands at the end.

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?

With no output schema, the description carries the return-value burden and does so: it names the cap, the fields, and the answer_kind values with their interpretation. Combined with fully documented parameters and annotations covering safety, an agent has everything needed to call it and to handle every result category correctly.

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 every one of the six parameters is already documented in the schema, including the cents convention and the session_id fallback. The description restates those filters (query, category, max price in cents, in stock) without adding syntax, defaults or precedence rules 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.

Purpose5/5

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, 'Search the shop catalogue', then enumerates the levers it searches with (words, category, max price in cents, in-stock only). This scope makes it visibly distinct from the cart_*, checkout_* and get_product siblings, which operate on an already-identified product or basket.

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?

It gives strong guidance on interpreting and acting on results, especially 'relaxed or related (NOT exact: only the closest, say so)' and 'none (nothing matches: say so, never offer unrelated products)', which is exactly the behavioural rule an agent needs. What it lacks is routing guidance between this tool and alternatives such as get_product, check_availability or list_categories when the agent already has an id or a category handle.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.