Skip to main content
Glama

Browse a category, brand or tag

kh_browse
Read-onlyIdempotent

Lists products by category, brand, or campaign tag with sorting, price-range and attribute filters, so you can find matching catalog items before fetching product details.

Instructions

List products of a category, brand(s) or campaign tag with sorting, price range and filters.

Pass at least one of category_id, brands or tag; filter ids come from kh_filters. Next: kh_product.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "kh_browse"
  }
}

Input Schema

NameRequiredDescriptionDefault
tagNoTag slug from kh_deals, e.g. 'festival-js'.
pageNoFrom 1.
sortNoBy payable price for cheapest / most_expensive.popular
limitNoProducts per page.
queryNoOptional keyword inside the listing.
brandsNoSlugs from kh_brands / kh_filters (OR), e.g. ['simple'].
colorsNoColor ids from kh_filters (OR), e.g. ['3'] (red).
facetsNoAttribute keys from kh_filters (AND), e.g. ['facetKey.skin-type:oily'].
max_priceNoMax payable price, Toman.
min_priceNoMin payable price, Toman.
category_idNoId from kh_categories / kh_search, e.g. 145.
in_stock_onlyNoOnly orderable products.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed38 schema fields changedv0.4.0
    • removedInput schema / properties / brands / anyOf
      Removed value: -[
      -  {
      -    "items": {
      -      "pattern": "^[A-Za-z0-9._-]{1,80}$",
      -      "type": "string"
      -    },
      -    "maxItems": 10,
      -    "type": "array"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • changedInput schema / properties / brands / description
      Previous value: -"Brand slugs from kh_brands / kh_filters (OR), e.g. ['simple', 'cerave']."New value: +"Slugs from kh_brands / kh_filters (OR), e.g. ['simple']."
    • addedInput schema / properties / brands / items
      Added value: +{
      +  "pattern": "^[A-Za-z0-9._-]{1,80}$",
      +  "type": "string"
      +}
    • addedInput schema / properties / brands / maxItems
      Added value: +10
    • addedInput schema / properties / brands / type
      Added value: +[
      +  "array",
      +  "null"
      +]
    • removedInput schema / properties / category_id / anyOf
      Removed value: -[
      -  {
      -    "maximum": 1000000,
      -    "minimum": 1,
      -    "type": "integer"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • changedInput schema / properties / category_id / description
      Previous value: -"Category id from kh_categories or kh_search, e.g. 145 (moisturizers)."New value: +"Id from kh_categories / kh_search, e.g. 145."
    • addedInput schema / properties / category_id / maximum
      Added value: +1000000
    • addedInput schema / properties / category_id / minimum
      Added value: +1
    • addedInput schema / properties / category_id / type
      Added value: +[
      +  "integer",
      +  "null"
      +]
    • removedInput schema / properties / colors / anyOf
      Removed value: -[
      -  {
      -    "items": {
      -      "pattern": "^\\d{1,6}$",
      -      "type": "string"
      -    },
      -    "maxItems": 10,
      -    "type": "array"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedInput schema / properties / colors / items
      Added value: +{
      +  "pattern": "^\\d{1,6}$",
      +  "type": "string"
      +}
    • addedInput schema / properties / colors / maxItems
      Added value: +10
    • addedInput schema / properties / colors / type
      Added value: +[
      +  "array",
      +  "null"
      +]
    • removedInput schema / properties / facets / anyOf
      Removed value: -[
      -  {
      -    "items": {
      -      "pattern": "^facetKey\\.[\\w.-]{1,60}:[\\w.-]{1,80}$",
      -      "type": "string"
      -    },
      -    "maxItems": 6,
      -    "type": "array"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedInput schema / properties / facets / items
      Added value: +{
      +  "pattern": "^facetKey\\.[\\w.-]{1,60}:[\\w.-]{1,80}$",
      +  "type": "string"
      +}
    • addedInput schema / properties / facets / maxItems
      Added value: +6
    • addedInput schema / properties / facets / type
      Added value: +[
      +  "array",
      +  "null"
      +]
    • changedInput schema / properties / in_stock_only / description
      Previous value: -"Only products that can be ordered now."New value: +"Only orderable products."
    • changedInput schema / properties / limit / description
      Previous value: -"Products per page (sponsored items are left out)."New value: +"Products per page."
    • removedInput schema / properties / max_price / anyOf
      Removed value: -[
      -  {
      -    "minimum": 1,
      -    "type": "integer"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • changedInput schema / properties / max_price / description
      Previous value: -"Maximum payable price in Toman, e.g. 1500000."New value: +"Max payable price, Toman."
    • addedInput schema / properties / max_price / minimum
      Added value: +1
    • addedInput schema / properties / max_price / type
      Added value: +[
      +  "integer",
      +  "null"
      +]
    • removedInput schema / properties / min_price / anyOf
      Removed value: -[
      -  {
      -    "minimum": 0,
      -    "type": "integer"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • changedInput schema / properties / min_price / description
      Previous value: -"Minimum payable price in Toman, e.g. 500000."New value: +"Min payable price, Toman."
    • addedInput schema / properties / min_price / minimum
      Added value: +0
    • addedInput schema / properties / min_price / type
      Added value: +[
      +  "integer",
      +  "null"
      +]
    • changedInput schema / properties / page / description
      Previous value: -"Page number, from 1."New value: +"From 1."
    • removedInput schema / properties / query / anyOf
      Removed value: -[
      -  {
      -    "maxLength": 100,
      -    "minLength": 2,
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedInput schema / properties / query / maxLength
      Added value: +100
    • addedInput schema / properties / query / minLength
      Added value: +2
    • addedInput schema / properties / query / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • changedInput schema / properties / sort / description
      Previous value: -"popular = site default; cheapest / most_expensive by payable price."New value: +"By payable price for cheapest / most_expensive."
    • removedInput schema / properties / tag / anyOf
      Removed value: -[
      -  {
      -    "pattern": "^[A-Za-z0-9._-]{1,80}$",
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • changedInput schema / properties / tag / description
      Previous value: -"Campaign tag slug from kh_deals, e.g. 'festival-js' (pink box)."New value: +"Tag slug from kh_deals, e.g. 'festival-js'."
    • addedInput schema / properties / tag / pattern
      Added value: +"^[A-Za-z0-9._-]{1,80}$"
    • addedInput schema / properties / tag / type
      Added value: +[
      +  "string",
      +  "null"
      +]
  2. Changed17 schema fields changedv0.2.0
    • removedInput schema / properties / brands / title
      Removed value: -"Brands"
    • removedInput schema / properties / category_id / title
      Removed value: -"Category Id"
    • removedInput schema / properties / colors / title
      Removed value: -"Colors"
    • changedInput schema / properties / facets / description
      Previous value: -"Attribute filter keys from kh_filters, all must match (AND), e.g. ['facetKey.skin-type:oily']."New value: +"Attribute keys from kh_filters (AND), e.g. ['facetKey.skin-type:oily']."
    • removedInput schema / properties / facets / title
      Removed value: -"Facets"
    • removedInput schema / properties / in_stock_only / title
      Removed value: -"In Stock Only"
    • removedInput schema / properties / limit / title
      Removed value: -"Limit"
    • removedInput schema / properties / max_price / title
      Removed value: -"Max Price"
    • removedInput schema / properties / min_price / title
      Removed value: -"Min Price"
    • removedInput schema / properties / page / title
      Removed value: -"Page"
    • removedInput schema / properties / query / title
      Removed value: -"Query"
    • changedInput schema / properties / sort / description
      Previous value: -"Order: popular (the site's default, most visited), cheapest / most_expensive (payable price), newest."New value: +"popular = site default; cheapest / most_expensive by payable price."
    • removedInput schema / properties / sort / title
      Removed value: -"Sort"
    • changedInput schema / properties / tag / description
      Previous value: -"Collection / campaign tag slug from kh_deals (the part after /tags/), e.g. 'festival-js' (pink box)."New value: +"Campaign tag slug from kh_deals, e.g. 'festival-js' (pink box)."
    • removedInput schema / properties / tag / title
      Removed value: -"Tag"
    • removedInput schema / title
      Removed value: -"kh_browseArguments"
    • changedOutput schema / (root)
      Previous value: -{
      -  "additionalProperties": true,
      -  "title": "kh_browseDictOutput",
      -  "type": "object"
      -}New value: +null
  3. First observedv0.1.0

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already declare this as a safe, read-only, idempotent, open-world operation. The description adds a non-schema behavioral constraint (at least one selector must be supplied) and points to kh_filters for valid ids, which is useful context. It does not describe pagination behavior, result shape, or other operational details beyond what the schema and annotations provide.

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 two short sentences with zero filler. The core scope is front-loaded, followed immediately by the key invocation constraint and the recommended next tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-parameter browsing tool with full schema coverage and safety annotations, the description captures the main selector constraint, dependency on kh_filters, and follow-up tool. It is nearly complete, though it could mention pagination or result-shape expectations more explicitly since there is no output schema.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already explains each parameter in detail. The description reinforces that category_id, brands and tag are the primary selectors and that filter ids come from kh_filters, but adds little parameter-level meaning beyond the schema.

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 uses a specific verb and resource: "List products of a category, brand(s) or campaign tag", and mentions sorting, price range and filters. This clearly distinguishes entity-based browsing from keyword search, though it does not explicitly contrast itself with siblings like kh_search or kh_find_cheapest.

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

Usage Guidelines3/5

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

The description gives an important invocation rule: "Pass at least one of category_id, brands or tag", and points to kh_filters for filter ids. It also names kh_product as the next tool. However, it does not say when to use this tool versus kh_search, kh_find_cheapest, or kh_deals, so alternative-selection guidance remains implicit.

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