Skip to main content
Glama

Storewire Lite demo store

Search products

search_products
Read-onlyIdempotent

Search the Trailhead Supply catalogue the way its search page does: by words or a model number, within a category or brand, by price in USD, in stock only, and by spec filters. Each product comes with its page URL, photo, price, stock line, key specs and category. The answer also gives the total, the same results' URL on the store's website, suggested_filters (categories and spec values with how many products each would leave) and, when nothing matches, did_you_mean with categories and products the store offers instead.

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
pageNoPage number (default 1).
sortNoOrder: relevance (default), price_asc, price_desc or newest.
brandNoA brand name.
limitNoProducts per page (default 10).
queryNoWords or a model number. Required unless category or brand is given.
localeNoAnswer language: en (default en). Names, labels and URLs follow it.
filtersNoSpec filters from suggested_filters: code => list of values, e.g. {"color": ["black"]}; a numeric spec also takes "min~max". At most 6 codes of 8 values each.
categoryNoA category slug from list_categories or suggested_filters.
in_stockNoOnly products in stock now.
price_maxNoHighest price in USD.
price_minNoLowest price in USD.

Output Schema

NameRequiredDescriptionDefault
urlYesThese results on the store's website.
pageYes
totalYesAll matching products, across pages.
per_pageYes
productsYes
truncatedNoPresent and true only when the answer outgrew the size budget and its last list items were left out; ask narrower to see them.
answer_typeNoWhat this answer is, for rendering.
did_you_meanYesOnly when nothing matched: what the store suggests instead.
applied_filtersYes
suggested_filtersYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered and the bar is lower. Beyond that, the description discloses genuinely non-annotated behavior: that the result set carries a total, a canonical storefront URL for re-running the same search, suggested_filters with per-value product counts, and a did_you_mean fallback when nothing matches. That is a real explanation of the tool's response contract and the fallback path, though it does not touch pagination cost, result-volume limits, or rate behavior.

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 facet list is correctly front-loaded in the first clause, which is the right structure. However, the second and third sentences largely restate the return payload (page URL, photo, price, stock line, specs, category, total, results URL, suggested_filters, did_you_mean) that an existing output schema already covers, so a meaningful share of the text does not earn its place against structured data. Density is high but partly redundant.

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?

For an 11-parameter tool with a nested filters object, required-none semantics and an output schema, the description covers the essential agent decisions: what inputs route to it, that prices are USD, that filters come from suggested_filters, and what happens on zero results. The output schema absorbs the return-value burden, so the remaining gap is minor — mainly no guidance on the query-vs-category/brand requirement or on page/limit interplay, both of which live in the schema.

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 schema already documents page, sort, brand, limit, query, locale, filters, category, in_stock and both price bounds including enum values and limits. The description adds only mild connective meaning: prices are in USD, filters are spec filters derived from suggested_filters, and query can be a model number. Baseline 3 applies because the schema is doing 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?

The description opens with a specific verb and resource ("Search the Trailhead Supply catalogue") and immediately enumerates the facets it accepts: words or model number, category, brand, price, in-stock, spec filters. It also frames the behavior as mirroring the store's own search page, so an agent knows this is a catalogue retrieval tool rather than a cart or comparison tool. It stops short of naming a sibling (e.g., get_product or show_products) to contrast against, so it is clear but not sibling-differentiating.

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?

Usage context is strong on the positive side: the phrase "the way its search page does" plus the facet list tells an agent exactly which request shapes this tool serves, including the keyword/category/brand entry points. The did_you_mean and suggested_filters behavior also signals it is the right tool for browsing when the query may not resolve. There is no explicit when-not guidance or pointer to the sibling tools that handle direct product lookup or comparison.

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.