Skip to main content
Glama

kapruka_search_products

Read-onlyIdempotent

Search for products on Kapruka.com by keyword, with optional category filter and pagination.

Returns a ranked list of matching products with prices, stock status, images, and URLs,
plus the category facets available for the query (facets.categories) — the names that
work in `category` to narrow the same search.
Supports cursor-based pagination — pass next_cursor from one response into the next call.
Pagination is capped at 3 pages per query to discourage catalog enumeration; for broader
discovery, refine the query or narrow with a facet instead.

Queries must be at least 3 characters and contain specific terms — pure stopword queries
(e.g. "the", "a an") are rejected.

Relevance: the API matches ANY single query word, so extra words add loosely related
results rather than narrowing. Search the thing the customer wants (the head noun) and
check the product names actually contain it before presenting them.

Prices and min_price/max_price are both in `currency` — pass the customer's own budget
in their own currency; do not convert it. Gifts for recipients OUTSIDE Sri Lanka are not
in this search: use kapruka_gift_countries / kapruka_gift_country_products. A row's `price` is the discounted price
checkout charges (the bounds filter on it); `compare_at_price` is set when on sale.

Search results carry NO delivery-scope information. Food, hotel cakes and liquor
are delivered only to selected cities — never infer deliverability from a search
hit. Before quoting delivery on a specific item, call kapruka_get_product (read
`delivery.island_wide`) or kapruka_check_delivery with `product_id`.

Args:
    params (SearchProductsInput):
        - q (str): Search query (e.g. 'birthday cake', 'roses', 'tea gift'). Min 3 chars.
        - category (Optional[str]): A facet name from a previous search's facets.categories
        - limit (int): Results per page, 1–50 (default 10)
        - cursor (Optional[str]): Pagination cursor from previous response
        - currency (str): LKR (default), USD, GBP, AUD, EUR
        - min_price (Optional[float]): Min price (inclusive) in `currency`
        - max_price (Optional[float]): Max price (inclusive) in `currency`
        - in_stock_only (bool): Restrict to in-stock items (default false)
        - sort (str): 'relevance' | 'price_asc' | 'price_desc' | 'newest' | 'bestseller'
        - include_stubs (bool): Deprecated, no effect
        - response_format (str): 'markdown' (default) or 'json'

Returns:
    str: Search results in the requested format.

    JSON schema:
    {
      "results": [
        {
          "id": str,
          "type": "product",
          "name": str,
          "summary": str,
          "price": {"amount": float | null, "currency": str},
          "compare_at_price": {"amount": float, "currency": str} | null,
          "in_stock": bool,
          "stock_level": str,
          "image_url": str | null,
          "category": {"id": str, "name": str, "slug": str},
          "rating": null,
          "ships_internationally": bool,
          "url": str
        }
      ],
      "next_cursor": str | null,     # null after page 3 even if upstream has more
      "total_estimate": int,         # index hits for the query words (any-word match)
      "applied_filters": {"q": str, "category": str, "currency": str, ...},
      "facets": {"categories": [{"name": str, "count": int}]},
      "category_filter_dropped": str,   # only when `category` was not a facet here
      "valid_categories": [str]         # ...and the facet names that are
    }

    Error: "Error: <message>" or "No products found for '<query>'" on failure.

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": {
      "params": "<params>"
    },
    "name": "kapruka_search_products"
  }
}

Input Schema

NameRequiredDescriptionDefault
paramsYes

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / $defs / SearchProductsInput / properties / category / description
      Previous value: -"Filter by SUBCATEGORY FACET NAME — the same value the website's search uses in its `subcat=` parameter and shows in its left sidebar, e.g. 'Kapruka Cakes', 'Fresh Flowers', 'Birthday', 'Greeting Cards', 'Cake And Flower', 'Home And Lifestyle', 'Grocery Items'. These are narrower than a department and the valid set DEPENDS ON THE QUERY. Department words ('Cakes', 'Flowers', 'Toys') and most values from kapruka_list_categories are NOT valid here and return nothing. When the filter matches nothing this tool retries without it and says so, so a wrong value costs relevance, not results. If unsure, leave it unset and put the words in `q`."New value: +"Filter by a SEARCH FACET name. Every search response lists the valid ones for its words under facets.categories (e.g. 'Kapruka Cakes', 'Fresh Flowers', 'Electronics', 'Mobile Phones', 'Greeting Cards') — search once without a category, then narrow with one of those names. Department words ('Cakes', 'Flowers') and names from kapruka_list_categories (the site's navigation, a different vocabulary) are NOT facet names. Case and spacing don't matter. A name that isn't a facet for this query is dropped: you get results without it plus the list of valid names."
    • changedInput schema / $defs / SearchProductsInput / properties / include_stubs / description
      Previous value: -"If false (default), category landing pages (CATSYM entries, price=0) are filtered out."New value: +"Deprecated, has no effect. Kept so existing callers don't break: since 2026-09-26 the API never returns category landing pages from a search."
  2. Changed1 schema field changed
    • changedInput schema / $defs / SearchProductsInput / properties / currency / description
      Previous value: -"Price currency. Supported: LKR, USD, GBP, AUD, CAD, EUR"New value: +"Price currency. Supported: LKR, USD, GBP, AUD, EUR"
  3. Changed1 schema field changed
    • changedInput schema / $defs / SearchProductsInput / properties / category / description
      Previous value: -"Filter by category name (e.g. 'Birthday', 'Cakes', 'Flowers'). Case-insensitive."New value: +"Filter by SUBCATEGORY FACET NAME — the same value the website's search uses in its `subcat=` parameter and shows in its left sidebar, e.g. 'Kapruka Cakes', 'Fresh Flowers', 'Birthday', 'Greeting Cards', 'Cake And Flower', 'Home And Lifestyle', 'Grocery Items'. These are narrower than a department and the valid set DEPENDS ON THE QUERY. Department words ('Cakes', 'Flowers', 'Toys') and most values from kapruka_list_categories are NOT valid here and return nothing. When the filter matches nothing this tool retries without it and says so, so a wrong value costs relevance, not results. If unsure, leave it unset and put the words in `q`."
  4. First observed

TDQS

A5/5.0
Behavior5/5

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

Annotations already cover readOnly, idempotent, openWorld, and non-destructive hints, but the description goes much further: pagination capped at 3 pages, stopword rejection, any-word matching semantics, the fact that search results carry no delivery-scope information, and the relationship between price and compare_at_price. This is exceptional disclosure beyond structured fields.

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?

The description is long but appropriately so given the tool's complexity and the low schema description coverage. It is front-loaded with the core search action, then proceeds through pagination, query rules, relevance, pricing, and delivery caveats in a logical order. Every sentence earns its place by providing necessary operational context.

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?

The description fully addresses the tool's complexity: it covers input parameters, output structure (with examples), pagination limits, query constraints, relevance behavior, currency handling, and delivery-scope limitations. Given the output schema is already provided, the description need not repeat return values, but it still clarifies key output fields like facets and compare_at_price.

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

Parameters5/5

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

Although the top-level schema description coverage is reported as 0%, the description compensates thoroughly by explaining every nested parameter: q minimum length and stopword rules, category as a facet name, limit range, cursor usage, currency behavior, price bounds, in_stock_only, sort options, include_stubs deprecation, and response_format. It adds substantial meaning beyond what the schema alone provides.

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 states a specific verb ('Search') and resource ('products on Kapruka.com') with clear scope ('by keyword, with optional category filter and pagination'). It distinguishes itself from siblings by explicitly naming alternatives like kapruka_gift_countries and kapruka_get_product for different use cases.

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

Usage Guidelines5/5

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

It gives explicit when-to-use and when-not-to-use guidance: 'Gifts for recipients OUTSIDE Sri Lanka are not in this search: use kapruka_gift_countries / kapruka_gift_country_products' and 'Before quoting delivery ... call kapruka_get_product ... or kapruka_check_delivery'. It also explains how to refine queries and use facets, leaving no ambiguity.

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.