Skip to main content
Glama
sepehr071

khanoumi-mcp

by sepehr071
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Filters of a listing

kh_filters
Read-onlyIdempotent

Retrieve available filters—sub-categories, brands, colors, attributes—with IDs, counts, price range and stock for any category, brand, tag, or search query.

Instructions

List the filters of a category, brand, tag or search: sub-categories, brands, colors and attribute facets (skin type, hair type, ingredients, ...) with ids and counts, plus price range and stock counts.

Use before kh_browse: pass brand slugs as brands, color ids as colors, facet keys as facets. Brands are cut to 40 and each group to 25 values (omitted = how many more); pass group to see one in full. price_range is on the list price before discount (min 0 = out-of-stock items).

Input Schema

NameRequiredDescriptionDefault
tagNoCampaign tag slug from kh_deals, e.g. 'festival-js' (pink box).
groupNoOnly attribute groups whose name contains this, listed in full, e.g. 'نوع پوست' (skin type).
queryNoKeyword, alone or inside the listing.
brandsNoBrand slugs from kh_brands / kh_filters (OR), e.g. ['simple', 'cerave'].
category_idNoCategory id from kh_categories or kh_search, e.g. 145 (moisturizers).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changedv0.2.0
    • removedInput schema / properties / brands / title
      Removed value: -"Brands"
    • removedInput schema / properties / category_id / title
      Removed value: -"Category Id"
    • changedInput schema / properties / group / description
      Previous value: -"Return only attribute groups whose name contains this, in full, e.g. 'نوع پوست' (skin type)."New value: +"Only attribute groups whose name contains this, listed in full, e.g. 'نوع پوست' (skin type)."
    • removedInput schema / properties / group / title
      Removed value: -"Group"
    • removedInput schema / properties / query / title
      Removed value: -"Query"
    • 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_filtersArguments"
    • changedOutput schema / (root)
      Previous value: -{
-  "additionalProperties": true,
-  "title": "kh_filtersDictOutput",
-  "type": "object"
-}New value: +null
  2. First observedv0.1.0

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description goes beyond them by disclosing truncation behavior (brands cut to 40, groups to 25 values, `omitted` counts the remainder) and the semantics of the returned price_range (list price pre-discount, min 0 meaning out-of-stock). It stops short of describing response shape or caching, which is why this is a 4 rather than a 5.

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?

Two dense paragraphs with the payload summary front-loaded and the usage/limits second. Every clause carries information, though the second paragraph packs truncation limits, price semantics and the group escape hatch into one long breath, which costs a little readability.

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

Completeness4/5

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

With no output schema, the description carries the burden of describing returns, and it does list the returned facets, counts, price range and stock counts plus truncation rules. What is left unstated is the behavior with zero arguments (all five params are optional) and whether the tool errors or returns unfiltered results, a gap for a no-required-param tool.

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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it maps output values onto specific parameters (slugs to brands, ids to colors, facet keys to facets) and explains that `group` lists a single attribute group in full. The `omitted`/truncation note also clarifies why group filtering exists.

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 ('List the filters') and enumerates the exact resource contents: sub-categories, brands, colors, attribute facets with ids and counts, plus price range and stock counts. It also disambiguates itself from kh_browse by positioning itself as the pre-browse step, so an agent can identify it without opening the 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?

'Use before kh_browse' gives explicit sequencing, and the follow-up sentence tells the agent exactly how to funnel the output forward: brand slugs as brands, color ids as colors, facet keys as facets. The `group` workaround for truncated groups is stated as a concrete condition, not left to inference.

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

Deploy Server

Other Tools