digikala-mcp

Overview Schema Source Related Servers Discussions Admin

Search products

dk_search

Read-onlyIdempotent

Search Digikala's catalog by product name, then narrow results by price, brand, color, seller, rating, and delivery, and sort them to compare available offers.

Instructions

Search products by name: price (Toman), discount, seller, rating, 20 per page.

Search also returns loosely related items: each product has match ('all', 'some' with missing_words, or 'none'); prefer 'all'. Filter ids come from dk_filters(query=...). sort=cheapest puts accessories first: use dk_find_cheapest for the cheapest real match. Next: dk_product for every seller's offer.

Input Schema

Name	Required	Description	Default
`page`	No	Page number, from 1 (20 products per page).
`sort`	No	Order of the results.	relevance
`query`	Yes	Product name or words, Persian or English, e.g. 'گوشی سامسونگ' or 'airpods pro'.
`colors`	No	Color ids from dk_filters, e.g. [1].
`brand_ids`	No	Brand ids from dk_product's brand_id or dk_brand_products' brand.id, e.g. [18] Samsung, [1662] Xiaomi.
`max_price`	No	Highest price in Toman, e.g. 50000000.
`min_price`	No	Lowest price in Toman, e.g. 10000000 for 10 million Toman.
`attributes`	No	Feature filters from dk_filters: {attribute id: [value ids]}, e.g. {2226: [19239]}. Values OR, attributes AND.
`seller_type`	No	Only offers from Digikala itself, official brand sellers, trusted sellers or rural (roosta) sellers.
`fast_delivery`	No	Only items with fast (Jet) delivery.
`in_stock_only`	No	Only products that can be bought now.
`ready_to_ship`	No	Only items already in Digikala's warehouse (ship sooner).

Schema Changelog

Changes observed during successful MCP inspections.

Changed16 schema fields changedv0.4.0Oct 17, 2026

changedInput schema / properties / attributes / anyOf

Previous value: -[
-  {
-    "additionalProperties": {
-      "items": {
-        "type": "integer"
-      },
-      "type": "array"
-    },
-    "maxProperties": 10,
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": {
+      "items": {
+        "type": "integer"
+      },
+      "maxItems": 20,
+      "type": "array"
+    },
+    "maxProperties": 10,
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / attributes / description

Previous value: -"Feature filters from dk_filters: {attribute id: [value ids]}, e.g. {2226: [19239]} for Android phones. Values of one attribute are OR'ed, attributes are AND'ed."New value: +"Feature filters from dk_filters: {attribute id: [value ids]}, e.g. {2226: [19239]}. Values OR, attributes AND."

removedInput schema / properties / attributes / title
```
Removed value: -"Attributes"
```
removedInput schema / properties / brand_ids / title
```
Removed value: -"Brand Ids"
```
removedInput schema / properties / colors / title
```
Removed value: -"Colors"
```
removedInput schema / properties / fast_delivery / title
```
Removed value: -"Fast Delivery"
```
removedInput schema / properties / in_stock_only / title
```
Removed value: -"In Stock Only"
```
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"
```
removedInput schema / properties / ready_to_ship / title
```
Removed value: -"Ready To Ship"
```
removedInput schema / properties / seller_type / title
```
Removed value: -"Seller Type"
```
removedInput schema / properties / sort / title
```
Removed value: -"Sort"
```
removedInput schema / title
```
Removed value: -"dk_searchArguments"
```

changedOutput schema / (root)

Previous value: -{
-  "additionalProperties": true,
-  "title": "dk_searchDictOutput",
-  "type": "object"
-}New value: +null

Changed5 schema fields changedv0.2.1Oct 5, 2026

addedInput schema / properties / attributes

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {
+        "items": {
+          "type": "integer"
+        },
+        "type": "array"
+      },
+      "maxProperties": 10,
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Feature filters from dk_filters: {attribute id: [value ids]}, e.g. {2226: [19239]} for Android phones. Values of one attribute are OR'ed, attributes are AND'ed.",
+  "title": "Attributes"
+}

addedInput schema / properties / colors

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "integer"
+      },
+      "maxItems": 10,
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Color ids from dk_filters, e.g. [1].",
+  "title": "Colors"
+}

addedInput schema / properties / fast_delivery

Added value: +{
+  "default": false,
+  "description": "Only items with fast (Jet) delivery.",
+  "title": "Fast Delivery",
+  "type": "boolean"
+}

addedInput schema / properties / ready_to_ship

Added value: +{
+  "default": false,
+  "description": "Only items already in Digikala's warehouse (ship sooner).",
+  "title": "Ready To Ship",
+  "type": "boolean"
+}

addedInput schema / properties / seller_type

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "digikala",
+        "official",
+        "trusted",
+        "roosta"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Only offers from Digikala itself, official brand sellers, trusted sellers or rural (roosta) sellers.",
+  "title": "Seller Type"
+}

First observedv0.1.0Oct 3, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Annotations already declare safe read-only, idempotent, open-world behavior, so the bar is lower. The description goes well beyond by disclosing 20 results per page, the 'match' field semantics ('all', 'some' with missing_words, 'none'), and the important sort=cheapest caveat.

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 search action and keeps the rest dense with match, filter, sort, and next-step information. It is appropriately sized with no filler, though some fragments are compressed enough to require careful parsing.

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 complex 12-parameter search tool with no output schema, the description covers key behavioral details: pagination, result match quality, and the next tool to call. It does not describe all return fields or pagination limits beyond page size, but schema and annotations cover the remaining structured concerns.

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 all 12 parameters are already documented, making 3 the baseline. The description adds only marginal parameter context, mainly that filter ids come from dk_filters(query=...) and restating price/seller/rating fields.

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: 'Search products by name', with scope details (price, discount, seller, rating, 20 per page). It also distinguishes itself from siblings by naming dk_find_cheapest for cheapest real matches and dk_product for seller offers.

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 clear usage context: filter ids come from dk_filters(query=...), sort=cheapest has a caveat directing to dk_find_cheapest, and 'Next: dk_product' tells the follow-up call. It lacks explicit when-not-to-use guidance against other search-like siblings such as dk_fresh_search or dk_category_products.

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

Search products

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools