Kapruka MCP

Name: Kapruka MCP
Author: kapruka

Server Details

Free public MCP server for Kapruka.com — Sri Lanka's largest e-commerce platform.

If you are the author of this connector, you can claim ownership by verifying the domain or GitHub account it belongs to. Claimed connector authors can inspect health checks, view analytics, and manage their listing.

Status: Healthy
Uptime: 100.0% over 74 days
Last Tested: 2026-10-31 19:25
Transport: Streamable HTTP · MCP 2025-11-25
URL
Repository: kapruka/mcp
GitHub Stars: 21
Server Listing: Kapruka MCP Server

TDQS

A4.6/5.0

Scored 2026-10-20 06:21 across 10 tools

Disambiguation5/5

Tools target clearly distinct resources and actions: search vs. get product, list vs. check delivery, domestic vs. international gifts, create vs. track order, and a dedicated card renderer. Descriptions and parameter sets make boundaries easy to distinguish, even though check_delivery is multi-modal.

Naming Consistency5/5

All tools use the kapruka_ prefix and snake_case with a verb_noun pattern (check_delivery, create_order, get_product, list_categories, render_options_card, search_products, track_order). Minor singular/plural variation in the gift tools (gift_countries vs. gift_country_products) does not break predictability.

Tool Count5/5

10 tools is well-scoped for an e-commerce gifting server, covering discovery, product detail, delivery validation, order creation, tracking, and international gifts without excessive surface. Each tool earns its place in the workflow.

Completeness3/5

Core workflows (search, get product, check delivery, create order, track order, international gifts) are covered. However, the surface references kapruka_custom_cake_request and kapruka_custom_cake_status without providing them, leaving custom cake orders as a dead end and potentially causing agent failures.

Available Tools

10 tools

kapruka_check_deliveryA

Read-only

Inspect

Check whether Kapruka can deliver to a given city on a given date, and the delivery fee.

Returns whether the requested date is available (if not, the next available
date plus reason) and the delivery fee the checkout will charge.

THE FEE DEPENDS ON THE CART AND THE CURRENCY — the city's base rate is not
what checkout charges. Sri Lankan customers (LKR) pay the city rate capped
by the cart value (25% of the item value, at least LKR 300; some remote
cities 50%), so a small cart to a far city pays far less than the rate.
Overseas customers (USD) pay a fixed USD fee per city, whatever the cart.
Pass `currency` and the `cart` you are about to order and the answer gives
the EXACT fee kapruka_create_order will charge ("Delivery fee for this
cart"). Without a cart, an LKR answer gives only the MOST the fee can be
("up to"). One shipment per order: the fee covers the whole cart.

Pass `product_id` whenever the customer has named a product: the answer then
also checks that ITEM's delivery scope (restaurant food, hotel cakes and
liquor only reach selected cities, typically the Colombo area). With a
product_id, `available` is true only if the date is open AND the item is
deliverable to that city. When `item_deliverable` is false, offer the
customer one of the returned `deliverable_cities` or an island-wide
alternative — do not attempt kapruka_create_order with the same city, it
will be rejected. An unknown product_id is silently ignored (no item fields
in the result), so check `item_deliverable` is present before relying on it.

product_id also selects the SAME-DAY rule the checkout applies to that item:
vendor-delivered items (restaurant food) can go today until late afternoon;
ordinary items move to the next date; ordinary same-day is only possible early
in the morning near Colombo. So a check without product_id can differ from one
with it — always pass it once an item is chosen. When `available` is false,
offer `next_available_date`. Do not interpret the `reason` text (it is the
website's wording and may say slots are full when the real cause is the cutoff).

ECONOMY DELIVERY (cheaper courier, a few days instead of a chosen date) is
worked out from the `cart` (and `gift_message`, which you should pass when
there is one). When the answer shows an economy option, offer it to the
customer as the cheaper choice, quoting its fee, promise wording and
"expected by" date as given; if they take it, call kapruka_create_order with
`delivery.type: "economy"` (the order is dated for you). When the answer says
the order goes by economy delivery, that is the ONLY option for these items:
tell the customer and order with `delivery.type: "economy"`. When economy is
not shown, do not mention it.

Perishable codes (CAKE*, FLOWER*, COMBO*) additionally get a freshness
warning when the chosen delivery date is more than 1 day out.

INTERNATIONAL GIFTS (store products from kapruka_gift_country_products): pass
product_id or cart (no city needed) and, for Australia / the UAE, `zone`. The
answer is that country's delivery: available or not, the fee for the whole order,
and the earliest date (3 days ahead; used when delivery_date is omitted).

Args:
    params (CheckDeliveryInput):
        - city (str): Canonical city name (e.g. 'Colombo 03', 'Galle'); not needed for
          international gift store products
        - zone (Optional[str]): international gifts in Australia / the UAE
        - delivery_date (Optional[str]): YYYY-MM-DD; defaults to today (LK time)
        - product_id (Optional[str]): Check the city against this item's delivery scope
        - currency (Optional[str]): LKR (default) or USD/GBP/AUD/EUR (charged in USD)
        - cart (Optional[list]): [{product_id, quantity, icing_text?}] for the exact fee
        - other_items_total (Optional[float]): LKR value of items not in `cart` (custom cake quote)
        - gift_message (Optional[str]): the order's gift message, for the economy rule
        - response_format (str): 'markdown' (default) or 'json'

Returns:
    str: Delivery feasibility + fee in the requested format.

    JSON schema:
    {
      "city": str,
      "now": str,                       # ISO timestamp, Sri Lanka time
      "checked_date": str,              # YYYY-MM-DD
      "available": bool,                # date open AND (if product_id) item deliverable
      "delivery_fee": number,           # what checkout charges (see fee_basis)
      "fee_currency": "LKR" | "USD",
      "fee_basis": "cart" | "max" | "fixed",  # exact for the cart | LKR without a cart: the most it can be | USD: same for any cart
      "fee_items_value": number,        # LKR item value the fee was computed from (fee_basis=cart)
      "fee_cart_error": str,            # the cart could not be priced (fee falls back to max)
      "rate": number,                   # the city's BASE rate (LKR) — not the checkout fee
      "currency": "LKR",
      "reason": str | null,             # date-block message, else "This item is not delivered to <City>."
      "next_available_date": str|null,  # only for date blocks
      "item_deliverable": bool,         # only when product_id resolved to a real product
      "deliverable_cities": [str],      # only when item_deliverable=false (capped at 60)
      "perishable_warning": str | null, # populated when product_id is perishable
      "economy": {                      # only with `cart`
        "available": bool,              # false: say nothing about economy
        "forced": bool,                 # true: economy is the ONLY option
        "fee": number, "currency": "LKR",
        "promise": str,                 # quote as given
        "delivery_date": str,           # "expected by" date; create_order uses it
        "saving": number | null         # vs the standard fee
      }
    }

Name	Required	Description	Default
`params`	Yes

Output Schema

Name	Required	Description
`result`	Yes

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already declare readOnlyHint/openWorldHint, so the bar is lower, yet the description adds real behavioral context: the fee is cart- and currency-dependent (25% cap, LKR 300 floor, 50% for some remote cities, fixed USD abroad), an unknown product_id is silently ignored so `item_deliverable` must be checked for presence, the same-day cutoff differs by vendor-delivered items, and the `reason` text must not be interpreted. These are non-obvious failure modes an agent could not infer from annotations or schema.

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?

Front-loaded with the core purpose, and the mid-section prose on fee mechanics is dense and earns its place. However the trailing 'Args' and 'Returns' blocks restate the input schema and the full output schema verbatim, which is redundant given `has output schema: true`. The result is far longer than needed for an agent that can read the structured fields.

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?

For a tool with fee logic, per-item delivery scope, currency branching, economy shipping, perishables and an international-gifts path, the description covers every branch an agent must handle, including the international case where no city is needed and a `zone` substitute applies. Nothing required to call it correctly is missing.

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

Parameters4/5

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

The nested schema already documents every field, and the description's Args block largely restates it. Where it earns credit is the added semantics: `cart`+`currency` change the answer from 'up to' to the exact fee, `other_items_total` covers custom cakes that cannot be priced as cart lines, and `gift_message` feeds the economy rule. Useful additions, though much is duplicated from the schema.

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?

Opens with a specific verb+resource+scope: 'Check whether Kapruka can deliver to a given city on a given date, and the delivery fee.' That is immediately distinguishable from siblings like kapruka_create_order (writes), kapruka_list_delivery_cities (enumerates cities) and kapruka_track_order. The description also names the downstream action it gates, so an agent can place it in the workflow without opening another schema.

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?

Explicit routing throughout: pass `product_id` whenever a customer names a product; pass `cart` and `currency` to get the exact checkout fee; if `item_deliverable` is false, 'do not attempt kapruka_create_order with the same city, it will be rejected' and instead offer `deliverable_cities`. It also states when to offer economy delivery (only when the answer shows it) and when to stay silent ('When economy is not shown, do not mention it'). When/when-not and the alternative action are both spelled out.

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

kapruka_create_orderA

Idempotent

Inspect

Create a guest-checkout order on Kapruka and return a click-to-pay link.

Builds a Kapruka order from the supplied cart + recipient + delivery + sender,
then returns a checkout URL the customer opens in a browser to complete payment.
No Kapruka account is required. Prices are locked for the lifetime of the link
(60 minutes) — the customer pays exactly the quoted grand total even if the
catalog price changes meanwhile.

Free public tier limits: 30 orders per hour per client IP. Cart up to 30 items,
quantity up to 99 per item. A fresh idempotency key is generated per call so
retries on transient errors return the same checkout URL rather than duplicates.

Args:
    params (CreateOrderInput):
        - cart (list[CartItem]): 1–30 lines. Catalogue line: product_id, quantity (default 1), optional icing_text (cakes only).
          Custom cake line: custom_cake_request_id + phone — orders the cake Kapruka staff quoted via
          kapruka_custom_cake_status (status must be 'quoted'; quantity is always 1; never send a price).
          Lines can be mixed in one order — one delivery fee covers everything; the whole cart must be
          deliverable to delivery.city. Only place a custom cake order after the customer clearly
          accepted the quoted total.
        - recipient (Recipient): name + phone (E.164 +9477… or local 077…)
        - delivery (Delivery): address, city (must be Kapruka-deliverable — use kapruka_list_delivery_cities), location_type (house/apartment/office/other, default house), date (YYYY-MM-DD, today-or-future Asia/Colombo), optional instructions, type ('standard' default | 'economy')
        - sender (Sender): name + anonymous flag
        - gift_message (Optional[str]): Up to 300 chars
        - currency (str): LKR (default), USD, GBP, AUD, EUR
        - response_format (str): 'markdown' (default) or 'json'

Returns:
    str: Order confirmation with checkout URL.

    JSON schema:
    {
      "checkout_url": str,           # Open in browser to pay (no login required)
      "order_ref": str,              # e.g. "ORD-20260520-7823"
      "order_id": str,               # id used by the bank-deposit flow
      "summary": {
        "items_total":   number,
        "delivery_fee":  number,
        "addons_total":  number,
        "grand_total":   number,     # items_total + delivery_fee + addons_total
        "currency":      str,
        "delivery_type": "standard" | "economy",
        "delivery_date": str,        # the date checkout will use — may differ from the one sent
        "delivery_promise": str      # economy only: quote as given
      },
      "expires_at": str              # ISO 8601 — link stops working after this
    }

    Error: "Error (<code>): <message>" on failure. Common codes:
      empty_cart, missing_field, past_delivery_date, product_not_found,
      product_out_of_stock, city_not_deliverable (city not in the network at
      all), date_not_deliverable, city_not_deliverable_for_item.

    Custom cake lines add: request_not_found (404 — wrong id/phone or staff
    removed it), quote_not_ready (409 — staff haven't priced it; check
    kapruka_custom_cake_status later), quote_expired (410 — submit a new
    kapruka_custom_cake_request). summary.items_total may differ from the
    quoted cake total by a few rupees (USD round-trip) — quote the summary
    numbers when asking for payment.

    economy_not_available (HTTP 422): economy was requested but this order
    cannot go economy. Nothing is created. Tell the customer it goes by
    standard delivery (fee from kapruka_check_delivery) and, once they agree,
    resend with delivery.type 'standard' and their date.

    Economy-only items always go economy, even when 'standard' is sent; read
    summary.delivery_type and summary.delivery_date and tell the customer the
    date checkout will use.

    city_not_deliverable_for_item (HTTP 422): at least one cart item (food /
    hotel cake / liquor) cannot reach delivery.city. NOTHING is created — the
    API never places a partial order and neither should you. The error text
    names every blocking item and lists the cities the whole cart CAN go to.
    Tell the customer which item blocks the order and offer to (a) change the
    city to one of those, or (b) remove/replace that item. Never retry with
    the same city. Avoid this entirely by calling kapruka_check_delivery with
    `product_id` for each limited item before ordering.

Name	Required	Description	Default
`params`	Yes

Output Schema

Name	Required	Description
`result`	Yes

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the annotations (idempotentHint, readOnlyHint=false), the description discloses operational traits the annotations cannot: per-call idempotency keys so retries return the same URL, 60-minute price lock, 30 orders/hour/IP rate limit, cart limits, and a catalog of error codes with recovery actions. It also states that no partial order is ever created, which is critical behavioral context for a mutating tool.

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?

It is long but front-loaded and organized under Args/Returns with clear error grouping, and nearly every sentence carries operational payload. The one weakness is that the Args section restates several field descriptions already present in the schema (e.g., icing_text, quantity range), which is mild redundancy rather than bloat.

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?

For a complex, multi-object ordering tool with rich annotations and an output schema, the description covers everything an agent needs: pre-flight checks, custom cake and economy workflows, error codes and remedies, and the fact that returned summary.delivery_type/date may differ from what was sent. Nothing material to correct invocation is missing.

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?

Despite the low schema-computed coverage, the description adds substantial meaning: the two mutually exclusive cart line shapes, the rule that lines can be mixed under one delivery fee, phone format examples (E.164 or local), location_type/type defaults, date semantics (Asia/Colombo, today-or-future), the currency allow-list, and the server-side substitution of quoted cake details. This is meaning well beyond field-level schema text.

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 first sentence gives a precise verb+resource+outcome: 'Create a guest-checkout order on Kapruka and return a click-to-pay link.' It also names the defining scope (guest checkout, no account needed), which separates it cleanly from sibling tools like kapruka_track_order or kapruka_check_delivery.

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 explicitly routes the agent to siblings and states preconditions: verify deliverability with kapruka_check_delivery per limited item before ordering, confirm custom cake status via kapruka_custom_cake_status ('quoted'), resolve cities via kapruka_list_delivery_cities, and send economy only after the customer agrees. It also states exclusions ('only place a custom cake order after the customer clearly accepted the quoted total', 'never retry with the same city').

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

kapruka_get_productA

Read-onlyIdempotent

Inspect

Fetch full details for a single Kapruka product by its product ID.

Returns name, description, price (with optional currency conversion), stock status,
images, variants, shipping info, delivery scope, and a direct product URL.

`economy_delivery` ("optional" | "only" | "only_5to7" | null) says whether the
item can go by the cheaper economy courier; kapruka_check_delivery with the
cart says whether an order is offered it.

International gift store products carry `international_gift` {"country", "orderable",
"store_url"}: they are delivered IN that country by Kapruka's partner (see
kapruka_gift_countries), not in Sri Lanka.

Discounts: `price` is what checkout charges, with any website discount already
applied; `compare_at_price` is the pre-discount price when one applies (null
otherwise). Each variant carries its own pair. Quote `price`.

Delivery scope: most gifts ship island-wide, but restaurant food, hotel cakes
and liquor only reach a limited city set (typically the Colombo area). The
`delivery` object is the authority — search results do NOT carry it. When
`delivery.island_wide` is false, tell the customer up front that the item is
delivered only to selected cities, and confirm their city with
kapruka_check_delivery(city, product_id) before promising anything. If
`deliverable_city_count` exceeds the returned list, the list is truncated —
say "and more", don't treat it as complete.

Note: Some IDs starting with 'CATSYM' are category landing pages, not purchasable
products — this tool will flag those clearly.

Args:
    params (GetProductInput):
        - product_id (str): Kapruka product ID (e.g. 'cakeXX000000')
        - currency (str): Price currency — LKR (default), USD, GBP, AUD, EUR
        - type (Optional[str]): Optional type hint (e.g. 'specialgifts')
        - response_format (str): 'markdown' (default) or 'json'

Returns:
    str: Product details in the requested format.

    JSON schema:
    {
      "id": str,
      "name": str,
      "description": str,
      "summary": str,
      "price": {"amount": float, "currency": str},
      "compare_at_price": {"amount": float, "currency": str} | null,
      "in_stock": bool,
      "stock_level": str,           # "low" | "medium" | "high"
      "category": {"id": str, "name": str, "slug": str, "path": str},
      "variants": [{"id": str, "name": str, "sku": str, "price": {...},
                    "in_stock": bool, "stock_level": str, "attributes": {...}}],
      "images": [str],              # list of full-resolution image URLs
      "attributes": {"type": str, "subtype": str, "weight": str, "vendor": str},
      "shipping": {"ships_from": str, "ships_internationally": bool, "restricted_countries": [str]},
      "delivery": {
        "island_wide": bool,
        "deliverable_city_count": int,   # only when island_wide=false; TRUE total
        "deliverable_cities": [str]      # only when island_wide=false; capped at 60
      },
      "rating": null,
      "url": str
    }

    Error: "Error: <message>" on failure.

Name	Required	Description	Default
`params`	Yes

Output Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior5/5

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

Annotations cover safety (readOnly, idempotent, non-destructive), so the description is free to add genuinely new behavior: discount semantics (price vs compare_at_price), delivery-scope narrowing for food/cakes/liquor, list truncation warning ('deliverable_city_count' is the true total), CATSYM category-landing-page flagging, and international-gift semantics. Rich context 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.

Conciseness4/5

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

Front-loads the one-line purpose, then return values, then behavioral caveats — well ordered. Docked slightly because the 'Returns' block reproduces the full JSON schema that already exists as an output schema, which is redundant padding.

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?

For a read tool with an output schema, the description covers the non-obvious edges an agent needs: discount quoting, delivery-scope authority, truncation, landing-page IDs, and error format. Nothing material is missing.

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

Parameters4/5

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

With low schema description coverage, the description documents each argument: product_id format ('cakeXX000000'), currency options (LKR/USD/GBP/AUD/EUR), optional type hint ('specialgifts'), and response_format markdown/json. Nearly compensates for the coverage gap, though it adds no format constraints beyond examples.

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?

States a specific verb and resource ('Fetch full details for a single Kapruka product by its product ID'), clearly distinguishing it from sibling kapruka_search_products. Scope ('single product by ID' vs. search) is unambiguous.

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?

Explicitly routes to siblings: kapruka_check_delivery for cart/economy delivery, kapruka_check_delivery(city, product_id) to confirm city before promising delivery, and kapruka_gift_countries for international gifts. Does not state an explicit 'use this instead of search_products when...' condition, so it falls just short of a full 5.

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

kapruka_gift_countriesA

Read-onlyIdempotent

Inspect

List the countries Kapruka delivers gifts IN (international gift stores).

Use when the RECIPIENT is outside Sri Lanka — e.g. "send flowers to my sister in
Dubai", "a cake for my son in Melbourne". These gifts are delivered by Kapruka's
partner in that country, not shipped from Sri Lanka. They are NOT in
kapruka_search_products; list a store with kapruka_gift_country_products.

For each country: how many gifts are in stock now (0 = nothing can be ordered
there right now — say so), the delivery fee (one fee per order, whatever the
number of items), and for Australia and the UAE the zones they deliver to —
delivery is ONLY to those zones, each with its own fee. The earliest delivery
date is 3 days from today (Sri Lanka date).

Args:
    params: currency ('LKR' default or 'USD'), response_format.

Returns:
    str. JSON: {"currency", "earliest_date", "countries": [{"country", "products_in_stock",
    "delivery_fee": {"amount","currency"}, "zone_required": bool,
    "zones": [{"name","delivery_fee"}], "earliest_date", "store_url"}]}

Name	Required	Description	Default
`params`	Yes

Output Schema

Name	Required	Description
`result`	Yes

TDQS

A4.8/5.0

Behavior5/5

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

Goes well beyond the safety annotations by disclosing the partner-fulfilment model (not shipped from Sri Lanka), the meaning of products_in_stock=0, fee-per-order semantics, the zone-restricted delivery for Australia/UAE, and the 3-day earliest-delivery policy.

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?

Dense but front-loaded: purpose, then when-to-use, then behavioral rules, then Args/Returns. Slightly long with heavy formatting, but nearly every sentence carries operational information.

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?

Covers routing, edge cases (zero stock, zone-only delivery), and even the return shape (though an output schema exists), leaving no gap an agent would need to call the tool correctly.

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

Parameters4/5

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

Schema description coverage is low, but the description restates both args (currency default LKR/USD, response_format) and adds the note that GBP/AUD/EUR are surfaced as USD, which is real semantics beyond the bare schema.

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?

States a specific verb and resource ('List the countries Kapruka delivers gifts IN') and immediately scopes it as international gift stores, which differentiates it from kapruka_list_delivery_cities and kapruka_search_products.

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?

Explicitly says when to use it (recipient outside Sri Lanka) with concrete examples, and names the two alternatives: kapruka_search_products (where these gifts do NOT appear) and kapruka_gift_country_products (to drill into a store).

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

kapruka_gift_country_productsA

Read-onlyIdempotent

Inspect

List EVERY gift in stock in one country's store (international gifts), grouped by type.

The stores are small (tens of products), so this returns the whole store: read it
and choose for the customer — there is no keyword search for these products.
Prices are exactly what checkout charges for the item (no website discounts apply
to these stores); delivery is extra — one fee per order (zone fee in Australia /
the UAE), shown at the top. Use the `id` with kapruka_get_product for full detail
and with kapruka_create_order (delivery.type "international_gift").

Args:
    params: country, type (optional filter), currency ('LKR' default or 'USD'),
        response_format.

Returns:
    str. JSON: {"country", "currency", "count", "delivery": {country row from
    kapruka_gift_countries}, "products": [{"id", "name", "type", "summary",
    "price": {"amount","currency"}, "image_url", "url"}]}

Name	Required	Description	Default
`params`	Yes

Output Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior5/5

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

Adds substantial context beyond the annotations: stores are small so the full catalog is returned, prices are exactly checkout charges with no website discounts, delivery is an extra per-order zone fee shown at the top, and the response shape is described. Annotations only cover safety/idempotency, so this pricing and delivery disclosure is genuinely additive.

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?

Front-loads the core purpose in the first sentence, then separates Args and Returns cleanly. Slightly verbose in the delivery/pricing sentence, but every clause conveys actionable information for ordering.

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?

Given a read-only catalog tool with an output schema, the description covers pricing semantics, delivery-fee behavior, the currency caveat, and the follow-up call path. An agent has everything needed to call it and use the results.

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

Parameters4/5

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

Enumerates the args (country, optional type filter, currency defaulting to LKR or USD, response_format). The reported schema coverage is 0%, so the description's listing is doing real work, though it adds little beyond the property descriptions themselves (e.g. no enumeration of valid type values here).

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?

States a precise verb+resource+scope: 'List EVERY gift in stock in one country's store (international gifts), grouped by type.' It also implicitly differentiates from kapruka_search_products by noting there is no keyword search for these stores.

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?

Gives clear context ('read it and choose for the customer') and routes the agent to follow-ups (use `id` with kapruka_get_product and kapruka_create_order with delivery.type 'international_gift'). It never explicitly contrasts when to prefer this over kapruka_search_products or kapruka_gift_countries as a first call, so it stops short of full alternative routing.

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

kapruka_list_categoriesA

Read-onlyIdempotent

Inspect

List top-level Kapruka product categories by name with browse URLs.

Returns the site's NAVIGATION categories plus the public Kapruka.com URL for each
category landing page — useful for sending a customer to a category to browse.

These names are NOT search filters. kapruka_search_products filters on search
facets, a different vocabulary (e.g. navigation 'Electronic' vs facet 'Electronics',
'Cakes' vs 'Kapruka Cakes'); every search response lists its valid facet names
under facets.categories. Use those for `category`, never these. Internal IDs and
product counts are not exposed. Results are cached for 30 minutes server-side.

Args:
    params (ListCategoriesInput):
        - depth (int): Sub-category levels to include, 1 or 2 (default 1)
        - response_format (str): 'markdown' (default) or 'json'

Returns:
    str: Category tree in the requested format.

    JSON schema:
    {
      "categories": [
        {
          "name": str,
          "url": str,                  # kapruka.com category landing page
          "children": [{"name": str, "url": str, "children": [...]}]
        }
      ]
    }

    Error: "Error: <message>" on failure.

Name	Required	Description	Default
`params`	Yes

Output Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior5/5

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

Despite readOnlyHint and idempotentHint annotations, the description adds valuable context: cache duration (30 minutes), that internal IDs and product counts are not exposed, and the exact error format. It also clarifies the data source (navigation vs facets).

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?

The description is somewhat verbose but well-structured: opening summary, usage guidance, parameter details, and return schema. It is front-loaded with the purpose and includes critical warnings. Minor redundancy in the JSON schema block, but overall earns its place.

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?

For a read-only listing tool with an output schema and strong annotations, the description is comprehensive. It covers what to do, what not to do, caching, error handling, and parameter details. Nothing essential is missing for correct invocation.

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

Parameters4/5

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

With schema description coverage at 0%, the description carries the burden. It explains depth levels (1 or 2) and response_format options (markdown/json), directly paralleling the schema fields, which compensates. Could add more but is effective.

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 clearly states the tool lists top-level product categories with names and URLs, a specific and distinct purpose. However, it doesn't explicitly contrast with siblings beyond the search distinction, so it's not a 5.

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?

Explicitly warns against using these names as search filters and directs the user to use facets.categories from search responses, naming the sibling kapruka_search_products. This is a clear 'when not to use' with alternatives.

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

kapruka_list_delivery_citiesA

Read-onlyIdempotent

Inspect

List or search Sri Lankan cities Kapruka delivers to.

Use the `query` param to filter (e.g. "colombo" → all Colombo zones,
"anur" → Anuradhapura). Without a query you get the first 25 cities
alphabetically, which is rarely what an agent needs — pass a query.

Returns canonical city names (use these as the `city` argument to
kapruka_check_delivery) plus any common aliases / vernacular spellings.

Args:
    params (ListDeliveryCitiesInput):
        - query (Optional[str]): Partial match filter
        - limit (int): Max results, 1–50 (default 25)
        - response_format (str): 'markdown' (default) or 'json'

Returns:
    str: Cities list in the requested format.

    JSON schema:
    {
      "cities": [{"name": str, "aliases": [str]}],
      "total_matched": int,
      "showing": int
    }

Name	Required	Description	Default
`params`	Yes

Output Schema

Name	Required	Description
`result`	Yes

TDQS

A4.7/5.0

Behavior5/5

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

Adds substantial behavioral detail beyond annotations: default shows first 25 cities alphabetically, query enables partial case-insensitive match, response_format can be markdown or json, and returns canonical names plus aliases. The caveat about the default being rarely needed is honest and useful.

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?

Well-structured and front-loaded: opening purpose, usage guidance, Args section, and Returns with JSON schema. Each sentence contributes relevant information without unnecessary verbosity.

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?

Given the tool's list/search functionality and available output schema, the description covers default behavior, filtering, response formats, and return structure. It even includes a JSON schema excerpt, making it complete for an agent to call correctly.

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

Parameters4/5

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

The description restates parameter names and types, but also adds illustrative examples and meaning beyond the schema. It explains the query behavior with concrete examples and clarifies that returned names should be used as the `city` argument, enriching parameter semantics.

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?

Clearly states it lists or searches Sri Lankan cities Kapruka delivers to, with a specific verb (list/search) and resource (cities). It distinguishes from sibling kapruka_check_delivery by noting it returns canonical city names to use as the `city` argument for that tool.

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?

Provides explicit usage guidance: warns that without a query the default alphabetical limit is rarely what an agent needs, and gives example filters ('colombo' → Colombo zones, 'anur' → Anuradhapura). It implies the relationship to kapruka_check_delivery but does not state when to avoid using this tool.

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

kapruka_render_options_cardA

Read-onlyIdempotent

Inspect

Render 1-4 products as ONE shareable JPEG "menu" card and return its URL.

The card shows each product's photo with a big numbered badge (the ref you
assign), and its name + price printed under the photo. Built for chat
commerce (WhatsApp): send the image, tell the customer "reply 1, 2 or 3",
and they pick without opening links. No AI is involved — the image is
server-composited from the live catalog data, so prices match what the
product tools return.

Ref numbering contract: refs are yours to assign — use sequential numbers
per conversation and NEVER reuse one (if the first card was 1-3, the next
card starts at 4). A number must keep meaning the same product for the whole
conversation.

Args:
    params (RenderOptionsCardInput):
        - items (list[CardProduct]): 1-4 of {product_id, ref}
        - currency (str): LKR (default), USD, GBP, AUD, EUR
        - courtesy ({currency, per_usd}, optional): home-currency figure printed
          under each USD price ("≈ JPY 2,544"); the caller's rate, echoed back
        - footer_note (str, optional): appended to the footer reply hint

Returns:
    str: JSON:
    {
      "card_url": str,              # public JPEG URL — send this as the image
      "items": [{"ref": int, "product_id": str, "name": str,
                  "price": {"amount": float, "currency": str},
                  "price_note": str | null, "url": str}],
      "courtesy": {"currency": str, "per_usd": float} | null,  # what was printed, or null
      "unavailable": [str]          # product_ids that failed to load (omitted from card)
    }

    Error: "Error: <message>" when no product could be loaded.

Name	Required	Description	Default
`params`	Yes

Output Schema

Name	Required	Description
`result`	Yes

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses meaningful behavior: server-side composition with no AI, live catalog pricing, the unavailable-products failure behavior, the 'Error: ...' return mode, and the critical ref-numbering never-reuse contract. These are details an agent could not infer from annotations or the schema alone.

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 well-structured: a one-line summary, a short use-case paragraph, the ref numbering contract, an Args breakdown, and a return contract. It is longer than average, but each section earns its place and the layout makes it highly scannable for an agent.

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 covers invocation constraints (1-4 items, sequential refs, currency behavior, courtesy rules), return shape (card_url, items, courtesy, unavailable), and error handling when no product loads. With the output schema also present, nothing essential is left for the agent to guess.

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 schema description coverage is reported at 0%, the description's Args block fully compensates: items as 1-4 of {product_id, ref}, currency options with LKR default, courtesy as the caller's rate echoed back under USD prices, and footer_note appended to the reply hint. It also explains the ref numbering contract, which is essential semantic guidance beyond the raw field names.

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 names a precise verb and resource: 'Render 1-4 products as ONE shareable JPEG menu card and return its URL.' It further narrows the purpose with the WhatsApp chat-commerce scenario, numbered ref badges, and the explicit statement that no AI is involved, distinguishing it from the product/search/order siblings.

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?

The description clearly explains when to use the tool: in chat commerce where the customer replies with a number, and notes that the image is server-composited from live catalog data so prices match what the product tools return. It does not explicitly name an alternative tool or a when-not-to-use condition, but the intended usage context is strongly implied.

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

kapruka_search_productsA

Read-onlyIdempotent

Inspect

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.

Name	Required	Description	Default
`params`	Yes

Output Schema

Name	Required	Description
`result`	Yes

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.

kapruka_track_orderA

Read-only

Inspect

Look up status and delivery progress for a Kapruka order by order number.

Returns current status (received / confirmed / out-for-delivery / delivered /
cancelled), the recipient and delivery details on file, a timestamped progress
timeline, the cart contents, and flags for whether a delivery photo or video is
available. Use this after a customer has placed and paid for an order and reads
back the order number from their confirmation email or the order complete page.

The order number is NOT the `order_ref` returned by kapruka_create_order
(which is the pre-payment checkout reference). Once the customer completes
payment in the browser, Kapruka emails them a separate order number — that
is what this tool expects.

Args:
    params (TrackOrderInput):
        - order_number (str): Kapruka order number (e.g. 'VIMP34456CB2')
        - response_format (str): 'markdown' (default) or 'json'

Returns:
    str: Order tracking details in the requested format.

    JSON schema:
    {
      "order_number": str,
      "pnref": str,                 # internal payment reference (numeric; not the same as order_number)
      "status": str,                # received | confirmed | shipped | delivered | cancelled | ...
      "status_display": str,        # human label
      "order_date": str,            # human-formatted, Asia/Colombo
      "delivery_date": str,         # human-formatted
      "shipped_date": str | null,
      "amount": str,                # LKR string (e.g. "15500.00")
      "payment_method": str,
      "comments": str | null,
      "recipient": {"name": str, "phone": str, "address": str, "city": str},
      "greeting_message": str | null,
      "special_instructions": str | null,
      "progress": [{"step": str, "timestamp": str}],
      "live_tracking_available": bool,
      "has_delivery_video": bool,
      "has_delivery_photo": bool,
      "items": [{"product_id": str, "name": str, "quantity": int, "selling_price": float}]
    }

    Error: "Error: <message>" on failure (e.g. order not found).

Name	Required	Description	Default
`params`	Yes

Output Schema

Name	Required	Description
`result`	Yes

TDQS

A4.7/5.0

Behavior5/5

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

The description goes far beyond the annotations by detailing the exact statuses returned, the contents of the progress timeline, availability of delivery photo/video flags, and the error message format. Even though readOnlyHint and destructiveHint are already provided, the description adds meaningful behavioral context (e.g., live_tracking_available boolean, payment reference field) that helps an agent anticipate results.

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 well-organized: it starts with the core purpose, provides usage context, lists parameters, and includes a return schema. Every sentence contributes value, and the structure makes it easy to scan. The embedded JSON schema is verbose but justified given the complex return payload.

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?

Given the tool's complexity (multiple statuses, nested recipient/items objects, error handling), the description is comprehensive. It explains when to use it, what input to provide, what output to expect, and includes the caveat about order_ref. The annotations and detailed schema round out the context, making the tool fully actionable.

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?

The description's Args section essentially mirrors the input schema, which already contains detailed descriptions for both parameters, including the crucial order_ref distinction. Thus, the description adds little new semantic meaning beyond what the schema provides. The example format ('VIMP34456CB2') is helpful but not a significant increment.

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 uses a specific verb ('Look up') and resource ('status and delivery progress for a Kapruka order by order number'), clearly distinguishing it from sibling tools like kapruka_create_order. It also outlines the exact output, making the purpose unmistakable.

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 explicitly states when to use the tool ('after a customer has placed and paid for an order and reads back the order number from their confirmation email or the order complete page') and warns against using the order_ref from kapruka_create_order. This provides clear when-to-use and when-not-to-use guidance, effectively differentiating it from related tools.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

4 tool updatesOct 20, 2026

Changedkapruka_check_delivery8 fields changed

addedInput schema / $defs / CheckDeliveryInput / properties / city / anyOf

Added value: +[
+  {
+    "maxLength": 100,
+    "minLength": 2,
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / $defs / CheckDeliveryInput / properties / city / default
```
Added value: +null
```

changedInput schema / $defs / CheckDeliveryInput / properties / city / description

Previous value: -"Canonical city name (use kapruka_list_delivery_cities to find one). Examples: 'Colombo 03', 'Anuradhapura', 'Galle'."New value: +"Canonical Sri Lanka city name (use kapruka_list_delivery_cities to find one). Examples: 'Colombo 03', 'Anuradhapura', 'Galle'. Required, except for international gift store products (their country comes from the item)."

removedInput schema / $defs / CheckDeliveryInput / properties / city / maxLength
```
Removed value: -100
```
removedInput schema / $defs / CheckDeliveryInput / properties / city / minLength
```
Removed value: -2
```
removedInput schema / $defs / CheckDeliveryInput / properties / city / type
```
Removed value: -"string"
```

addedInput schema / $defs / CheckDeliveryInput / properties / zone

Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 60,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "International gifts only: the recipient's zone in Australia or the UAE, from kapruka_gift_countries (e.g. 'Dubai', 'Dandenong').",
+  "title": "Zone"
+}

removedInput schema / $defs / CheckDeliveryInput / required
```
Removed value: -[
-  "city"
-]
```

Changedkapruka_create_order6 fields changed

changedInput schema / $defs / Delivery / properties / city / description

Previous value: -"Must be a Kapruka delivery city (canonical name from kapruka_list_delivery_cities) that EVERY cart item can reach. The order ships as one shipment, so food / hotel cake / liquor items restrict the whole cart to their city set — verify with kapruka_check_delivery(city, product_id) first; otherwise the order is rejected with city_not_deliverable_for_item."New value: +"Sri Lanka orders: a Kapruka delivery city (canonical name from kapruka_list_delivery_cities) that EVERY cart item can reach. International gifts: the recipient's city/town abroad, as written. The order ships as one shipment, so food / hotel cake / liquor items restrict the whole cart to their city set — verify with kapruka_check_delivery(city, product_id) first; otherwise the order is rejected with city_not_deliverable_for_item."

addedInput schema / $defs / Delivery / properties / country

Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 60,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "International gifts only (required): the store country from kapruka_gift_countries.",
+  "title": "Country"
+}

changedInput schema / $defs / Delivery / properties / type / description

Previous value: -"'standard' (default) or 'economy' — the cheaper courier option. Send 'economy' only when kapruka_check_delivery (with the cart) showed it and the customer chose it, or said the items go by economy only. Economy orders are dated 4 days ahead for you; `date` is then ignored."New value: +"'international_gift' for products from kapruka_gift_country_products (recipient abroad; needs country, zip, zone where listed; date >= 3 days ahead). Otherwise 'standard' (default) or 'economy' — the cheaper courier option. Send 'economy' only when kapruka_check_delivery (with the cart) showed it and the customer chose it, or said the items go by economy only. Economy orders are dated 4 days ahead for you; `date` is then ignored."

addedInput schema / $defs / Delivery / properties / zip

Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 35,
+      "minLength": 1,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "International gifts only (required): the recipient's postcode / ZIP.",
+  "title": "Zip"
+}

addedInput schema / $defs / Delivery / properties / zone

Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 60,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "International gifts only: required for Australia and the UAE — one of that country's listed zones (kapruka_gift_countries).",
+  "title": "Zone"
+}

addedInput schema / $defs / Sender / properties / email

Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 120,
+      "pattern": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Sender's email (international gifts: send it when you have it).",
+  "title": "Email"
+}

Addedkapruka_gift_countries
Addedkapruka_gift_country_products

2 tool updatesOct 13, 2026

Changedkapruka_check_delivery1 field changed

addedInput schema / $defs / CheckDeliveryInput / properties / gift_message

Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 300,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "The gift message you will send to kapruka_create_order, if any. Pass it with `cart` so the economy delivery option is worked out the way checkout will.",
+  "title": "Gift Message"
+}

Changedkapruka_create_order1 field changed

addedInput schema / $defs / Delivery / properties / type

Added value: +{
+  "default": "standard",
+  "description": "'standard' (default) or 'economy' — the cheaper courier option. Send 'economy' only when kapruka_check_delivery (with the cart) showed it and the customer chose it, or said the items go by economy only. Economy orders are dated 4 days ahead for you; `date` is then ignored.",
+  "title": "Type",
+  "type": "string"
+}

1 tool updateOct 3, 2026

Changedkapruka_check_delivery4 fields changed

addedInput schema / $defs / CheckDeliveryInput / properties / cart

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "$ref": "#/$defs/DeliveryCartLine"
+      },
+      "maxItems": 30,
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "The items the customer is buying (product_id, quantity, optional icing_text) — the same lines you will send to kapruka_create_order. With it the answer gives the EXACT delivery fee checkout will charge; without it, only the most it can be.",
+  "title": "Cart"
+}

addedInput schema / $defs / CheckDeliveryInput / properties / currency

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "The currency the customer will check out in (LKR or USD; GBP/AUD/EUR check out in USD). Decides which delivery fee applies: Sri Lankan customers pay a fee capped by the cart value, overseas customers a fixed USD fee. Default LKR.",
+  "title": "Currency"
+}

addedInput schema / $defs / CheckDeliveryInput / properties / other_items_total

Added value: +{
+  "anyOf": [
+    {
+      "minimum": 0,
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "LKR value of items not listed in `cart` (e.g. a quoted custom cake's total). Added to the cart value for the fee.",
+  "title": "Other Items Total"
+}

addedInput schema / $defs / DeliveryCartLine

Added value: +{
+  "description": "A catalogue cart line, the same shape kapruka_create_order takes.\n\nCustom cake lines cannot be priced here; pass the quote's total as\n`other_items_total` instead.",
+  "properties": {
+    "icing_text": {
+      "anyOf": [
+        {
+          "maxLength": 120,
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "Set when the cake carries icing text — the checkout adds a small charge for it.",
+      "title": "Icing Text"
+    },
+    "product_id": {
+      "maxLength": 50,
+      "minLength": 3,
+      "pattern": "^[A-Za-z0-9_\\-]+$",
+      "title": "Product Id",
+      "type": "string"
+    },
+    "quantity": {
+      "default": 1,
+      "maximum": 99,
+      "minimum": 1,
+      "title": "Quantity",
+      "type": "integer"
+    }
+  },
+  "required": [
+    "product_id"
+  ],
+  "title": "DeliveryCartLine",
+  "type": "object"
+}

1 tool updateSep 26, 2026

Changedkapruka_search_products2 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."

4 tool updatesSep 21, 2026

Changedkapruka_create_order1 field changed

changedInput schema / $defs / CreateOrderInput / properties / currency / description

Previous value: -"Pricing currency. Supported: LKR, USD, GBP, AUD, CAD, EUR."New value: +"Pricing currency. Supported: LKR, USD, GBP, AUD, EUR."

Changedkapruka_get_product1 field changed

changedInput schema / $defs / GetProductInput / properties / currency / description

Previous value: -"Price currency. Supported: LKR, USD, GBP, AUD, CAD, EUR"New value: +"Price currency. Supported: LKR, USD, GBP, AUD, EUR"

Changedkapruka_render_options_card1 field changed
- changedInput schema / $defs / RenderOptionsCardInput / properties / currency / description
```
Previous value: -"Price currency: LKR, USD, GBP, AUD, CAD, EUR."New value: +"Price currency: LKR, USD, GBP, AUD, EUR."
```

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

1 tool updateSep 20, 2026

Changedkapruka_search_products1 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`."

1 tool updateSep 19, 2026

Changedkapruka_render_options_card3 fields changed

addedInput schema / $defs / Courtesy

Added value: +{
+  "additionalProperties": false,
+  "description": "A home-currency approximation to print under each USD price.\n\nThe CALLER supplies the rate it used for its own chat text, so the card and\nthe text agree to the unit; the card never converts on its own. Only\napplied when the card is priced in USD — the courtesy figure describes\nwhat a USD charge will look like on the customer's statement.",
+  "properties": {
+    "currency": {
+      "description": "ISO-4217 code of the customer's home currency, e.g. JPY.",
+      "maxLength": 3,
+      "minLength": 3,
+      "pattern": "^[A-Za-z]{3}$",
+      "title": "Currency",
+      "type": "string"
+    },
+    "per_usd": {
+      "description": "Units of that currency per 1 USD, as used for the chat text.",
+      "exclusiveMaximum": 1000000,
+      "exclusiveMinimum": 0,
+      "title": "Per Usd",
+      "type": "number"
+    }
+  },
+  "required": [
+    "currency",
+    "per_usd"
+  ],
+  "title": "Courtesy",
+  "type": "object"
+}

addedInput schema / $defs / RenderOptionsCardInput / properties / courtesy

Added value: +{
+  "anyOf": [
+    {
+      "$ref": "#/$defs/Courtesy"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional: print '≈ <home currency>' under each USD price (see Courtesy). Ignored unless currency is USD."
+}

addedInput schema / $defs / RenderOptionsCardInput / properties / footer_note

Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 60,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional short note appended to the footer's reply hint, e.g. 'Checkout charges USD'.",
+  "title": "Footer Note"
+}

1 tool updateSep 18, 2026

Changedkapruka_create_order17 fields changed

addedInput schema / $defs / CartItem / description

Added value: +"One cart line — EITHER a catalogue product OR a quoted custom cake.\n\nCatalogue line:   {\"product_id\": \"...\", \"quantity\": 1, \"icing_text\": \"...\"}\nCustom cake line: {\"custom_cake_request_id\": \"...\", \"phone\": \"+9477...\"}\nThe custom cake line is turned into the staff-quoted cake server-side\n(name, picture, price); quantity is always 1 and no price is ever sent."

addedInput schema / $defs / CartItem / properties / custom_cake_request_id

Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 80,
+      "minLength": 6,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "request_id of a custom cake that kapruka_custom_cake_status reports as 'quoted'. Orders the staff-quoted cake (quantity 1). Requires `phone`.",
+  "title": "Custom Cake Request Id"
+}

changedInput schema / $defs / CartItem / properties / icing_text / description

Previous value: -"Cake icing text. Silently ignored for non-cake products."New value: +"Cake icing text. Silently ignored for non-cake products. Catalogue lines only."

addedInput schema / $defs / CartItem / properties / phone

Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 30,
+      "minLength": 7,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "The customer.phone the custom cake request was made with (custom cake lines only).",
+  "title": "Phone"
+}

addedInput schema / $defs / CartItem / properties / product_id / anyOf

Added value: +[
+  {
+    "maxLength": 80,
+    "minLength": 3,
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / $defs / CartItem / properties / product_id / default
```
Added value: +null
```

changedInput schema / $defs / CartItem / properties / product_id / description

Previous value: -"Kapruka product ID (e.g. 'cakeXX000000')."New value: +"Kapruka product ID (e.g. 'cakeXX000000'). Catalogue line."

removedInput schema / $defs / CartItem / properties / product_id / maxLength
```
Removed value: -80
```
removedInput schema / $defs / CartItem / properties / product_id / minLength
```
Removed value: -3
```
removedInput schema / $defs / CartItem / properties / product_id / type
```
Removed value: -"string"
```

addedInput schema / $defs / CartItem / properties / quantity / anyOf

Added value: +[
+  {
+    "maximum": 99,
+    "minimum": 1,
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / $defs / CartItem / properties / quantity / default
```
Previous value: -1New value: +null
```

changedInput schema / $defs / CartItem / properties / quantity / description

Previous value: -"Quantity (1–99)."New value: +"Quantity (1–99, default 1). Catalogue lines only."

removedInput schema / $defs / CartItem / properties / quantity / maximum
```
Removed value: -99
```
removedInput schema / $defs / CartItem / properties / quantity / minimum
```
Removed value: -1
```
removedInput schema / $defs / CartItem / properties / quantity / type
```
Removed value: -"integer"
```
removedInput schema / $defs / CartItem / required
```
Removed value: -[
-  "product_id"
-]
```

2 tool updatesSep 11, 2026

Changedkapruka_check_delivery2 fields changed

changedInput schema / $defs / CheckDeliveryInput / properties / product_id / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "maxLength": 80,
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / $defs / CheckDeliveryInput / properties / product_id / description

Previous value: -"Optional product ID. If provided and the product looks perishable (cake/flower/combo codes), a freshness warning is added when the chosen date is more than 1 day out."New value: +"Product ID to check the city AGAINST THAT ITEM'S delivery scope. Food, hotel cakes and liquor only reach selected cities — always pass this when a customer names a product and a city, and only promise delivery if `available` is true. Also adds a freshness warning for perishable codes (cake/flower/combo) when the date is >1 day out."

Changedkapruka_create_order1 field changed

changedInput schema / $defs / Delivery / properties / city / description

Previous value: -"Must be a Kapruka delivery city — use kapruka_list_delivery_cities to look up valid names."New value: +"Must be a Kapruka delivery city (canonical name from kapruka_list_delivery_cities) that EVERY cart item can reach. The order ships as one shipment, so food / hotel cake / liquor items restrict the whole cart to their city set — verify with kapruka_check_delivery(city, product_id) first; otherwise the order is rejected with city_not_deliverable_for_item."

2 tool updatesAug 4, 2026

Changedkapruka_create_order1 field changed

changedInput schema / $defs / CartItem / properties / product_id / description

Previous value: -"Kapruka product ID (e.g. 'cake00ka002034')."New value: +"Kapruka product ID (e.g. 'cakeXX000000')."

Changedkapruka_get_product1 field changed

changedInput schema / $defs / GetProductInput / properties / product_id / description

Previous value: -"Kapruka product ID (e.g. 'cake00ka002034', 'EF_PC_CHOC0V2774P00065')"New value: +"Kapruka product ID (e.g. 'cakeXX000000', 'EF_PC_CHOC0V2774P00065')"

3 tool updatesAug 4, 2026
- Removedkapruka_customer_addresses
- Removedkapruka_customer_details
- Removedkapruka_order_history
3 tool updatesAug 4, 2026
- Addedkapruka_customer_addresses
- Addedkapruka_customer_details
- Addedkapruka_order_history
1 tool updateAug 3, 2026
- Addedkapruka_render_options_card
1 tool updateMay 25, 2026
- Addedkapruka_track_order
1 tool updateMay 23, 2026
- Addedkapruka_create_order
5 tool updatesMay 6, 2026
- First observedkapruka_check_delivery
- First observedkapruka_get_product
- First observedkapruka_list_categories
- First observedkapruka_list_delivery_cities
- First observedkapruka_search_products

Related MCP Connectors

hithereiamaliff-mcp-datagovmy BOAuth
ai.smithery
This MCP server provides seamless access to Malaysia's government open data, including datasets, w…
Government Data Open Data
3123
https://server.smithery.ai/@hithereiamaliff/mcp-datagovmy/mcp
BoxToPlayOAuth
com.boxtoplay
MCP-ready hosting provider for Minecraft, BungeeCord, TeamSpeak, VPS and many other game servers.
Games & Gamification Cloud Platforms Virtualization
2
https://api.boxtoplay.com/mcp
MAQAMI Travel B
io.github.negm17111995
Official MCP server for MAQAMI, a hotel and flight booking platform with 3M+ hotels.
E-commerce & Retail Travel & Transportation
4112
https://mcp.maqami.co/
registry A
io.github.urnetwork
Cloud-hosted MCP server for URnetwork VPN and Proxy
Cloud Platforms Security App Automation
2
https://mcp.bringyour.com

Related MCP Servers

OpenProject CE MCP Server
Product Management Project Management Workplace & Productivity
kar-thik
A
license
A
quality
A
maintenance
Open source MCP server for OpenProject aimed at community edition users
Updated 2 days ago (2026-10-29 18:23 UTC)
59
396 PyPI
6
MIT
Cuprice MCP Server
E-commerce & Retail Payments & Billing Marketing
eynullabeyli
A
license
Not graded
quality
C
maintenance
Public MCP server for integrating Cuprice pricing widgets from AI tools like Cursor, Claude Desktop, and Claude Code.
Updated 8 days ago (2026-10-23 20:28 UTC)
1
MIT
Finance Tools MCP
Finance Research & Data
VoxLink-org
A
license
B
quality
D
maintenance
An MCP server that provides comprehensive financial insights and analysis by leveraging real-time market data, news, and advanced analytics for stocks, options, financial statements, and economic indicators.
Updated a year ago (2025-09-13 17:52 UTC)
17
51
Python
MIT
Melbis Shopofficial
E-commerce & Retail Content Management Systems Security
melbis
F
license
B
quality
A
maintenance
Official MCP server of Melbis Shop, a self-hosted e-commerce platform: an AI agent works in the store as an employee — project files with version history, database, catalogue trees, product files and storefront pages — under a staff login with per-command permissions. Ships with the Windows client; 56 built-in tools plus store-specific tools with a permission on every command.
Updated 2 days ago (2026-10-29 12:02 UTC)
56
3
-

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Server Details

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Related MCP Connectors

Related MCP Servers

Melbis Shopofficial

Glama MCP Gateway

Resources