Skip to main content
Glama
catalog-mcp

catalog-mcp

by Yehiak

Search products

search_products
Read-onlyIdempotent

Find product IDs and matching catalog items by query, brand, category, price, and rating; filters apply before ranking, returning titles, brands, prices, and ratings.

Instructions

Search the product catalog and return the best matches with id, title, brand, price and rating.

Use this first to find product ids. Filters are applied before ranking.

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
modeNo'hybrid' (default, best overall) fuses keyword and semantic ranks; 'keyword' is BM25 full-text, best for exact model or part numbers; 'semantic' matches meaning, best for descriptive queries.hybrid
brandNoCase-insensitive substring of the brand or store name.
limitNoNumber of results (1-50).
queryYesWhat the user is looking for, in their own words or as keywords.
categoryNoRestrict to one category, e.g. 'Appliances' or 'Video_Games'. See catalog://stats.
max_priceNoMaximum price in USD. Products without a price are excluded when set.
min_priceNoMinimum price in USD. Products without a price are excluded when set.
min_ratingNoMinimum average star rating (0-5).

Output Schema

NameRequiredDescriptionDefault
modeYes
countYes
queryYes
resultsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.8/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds one real behavioral fact — filters are applied before ranking, so the result count reflects the filtered set rather than raw matches — but says nothing about scoring, pagination, or what happens when filters are over-restrictive.

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

Conciseness5/5

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

Two short sentences. The primary action and return shape come first, then the workflow hint and the ranking note. Nothing is redundant and nothing is buried.

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 full schema coverage, rich annotations and an output schema, the description needs only to establish scope and routing, which it does. The only gaps are the absent route to the sibling tools and the unmentioned catalog://stats resource referenced by the category parameter.

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%, with mode, brand, price bounds, rating and limit all documented inline, so the baseline is 3. The description adds no meaning beyond the schema for any of the eight parameters; "Filters are applied before ranking" is behavioral rather than parameter-level detail.

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?

"Search the product catalog and return the best matches" gives a specific verb plus resource, and it names the return fields (id, title, brand, price, rating). It does not name a sibling (get_product, compare_products, find_near_duplicates), so differentiation is implied through the id-lookup hint rather than stated.

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?

"Use this first to find product ids" positions the tool at the start of a workflow and tells the agent the downstream id dependency, which is genuine when-to-use guidance. There is no when-not guidance and no explicit routing to alternatives such as compare_products or find_near_duplicates.

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