Skip to main content
Glama
rezashahnazar

Digikala MCP Server

by rezashahnazar
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Digikala MCP Server

A Model Context Protocol (MCP) server for intelligent product discovery on Digikala, Iran's largest e-commerce platform.

🎯 Key Features

  • Intelligent Discovery Workflow: Iterative search refinement with query optimization

  • Bilingual Search: Automatic Persian (Farsi) and English query support

  • Simplified Results: Returns only marketable products with clean, structured data

  • Smart Ratings: Star ratings (0-5) only shown when statistically significant (10+ reviews)

  • Comprehensive Tools: Search, details, recommendations, and AI-powered semantic search

Related MCP server: Agentic Product Protocol MCP Server

💰 Currency Handling

All price inputs and outputs use TOOMAN currency (Iranian common currency).

  • User-facing: All price parameters accept Toomans

  • API conversion: Automatically converts to Rials (1 Tooman = 10 Rials) internally

  • Dual output: Product prices returned in both Tooman and Rial for transparency

Example:

# Input: Category ID and keyword (from get_optimized_keywords_and_categories), Price in Toomans
search_products(category_id=22, keyword="laptop", price_min_tooman=5000000, price_max_tooman=20000000)

# Output: Both currencies (simplified, parsed)
{
  "id": 12345,
  "title_fa": "لپ تاپ ایسوس",
  "selling_price_tooman": 1525000,  # 1.525M Toomans
  "selling_price_rial": 15250000,   # 15.25M Rials
  "rating_stars": 4.3,               # Out of 5 (only if 10+ reviews)
  "rating_count": 156
}

🔍 Discovery Workflow

This server implements an intelligent discovery workflow:

  1. Query Optimization: Use get_optimized_keywords_and_categories with both Persian and English queries

  2. Iterative Search: Execute search_products with category_id and keyword pairs from step 1

  3. Refine Results: Adjust sorting, pagination, or filters based on results

  4. Deep Dive: Use get_product_details for promising candidates

  5. Expand Search: Use get_product_recommendations for similar products

  6. Visual Search: Use search_text_lenz for clothing/accessories with descriptive queries

🛠️ Available Tools

1. get_optimized_keywords_and_categories

Query optimization and category discovery

  • Purpose: Get optimized search keywords and relevant category IDs

  • When to use: ALWAYS call this BEFORE search_products

  • Bilingual: Call with BOTH Persian (Farsi) and English queries separately

  • Parameters:

    • query (string): Single word query (e.g., 'laptop', 'phone', 'shoe')

  • Returns: Optimized keywords, category IDs, and codes

Example:

# Persian query (single word)
result_fa = get_optimized_keywords_and_categories("لپتاپ")
# English query (single word)
result_en = get_optimized_keywords_and_categories("laptop")

# Returns keyword-category pairs like:
# {"optimized_queries": ["laptop", "gaming laptop"], "categories": [{"id": 22, ...}]}

# Use these keyword-category pairs in search_products

2. search_products

Core product search with filtering (Uses Search API V2)

  • Purpose: Search products within a specific category with advanced filters and sorting

  • Returns: 20 simplified, marketable products per page

  • Critical: Call get_optimized_keywords_and_categories FIRST to get category_id

  • Required: Both category_id and keyword (from step 1 keyword-category pairs)

  • Parameters:

    • category_id (int): REQUIRED - Category ID from get_optimized_keywords_and_categories

    • keyword (string): REQUIRED - Search keyword from get_optimized_keywords_and_categories

    • page (int): Page number (default: 1)

    • sort (int): Sort order (default: 1)

      • 1: Relevance (default)

      • 2: Price Low to High

      • 3: Price High to Low

      • 4: Newest

      • 5: Best Selling

      • 6: Most Viewed

      • 7: Highest Rated

    • price_min_tooman (int): Minimum price in Toomans

    • price_max_tooman (int): Maximum price in Toomans

    • discount_min (int): Minimum discount %

    • discount_max (int): Maximum discount %

    • colors (list[int]): Color filter IDs

Returns: Simplified product list with:

  • id, title_fa, title_en, url

  • selling_price_tooman, selling_price_rial

  • rating_stars (0-5, only if 10+ reviews, otherwise None)

  • rating_count, brand, category

  • discount_percent, is_incredible, is_digiplus_jet_eligible

3. get_product_details

Comprehensive product information

  • Purpose: Deep dive into specific products

  • When to use: After finding promising candidates in search results

  • Parameters:

    • product_id (int): Product ID from search results

  • Returns: Parsed product details including:

    • Basic info (title, category, brand, URL)

    • Pricing (with Tooman/Rial)

    • Star ratings (0-5, if 10+ reviews)

    • Expert review description

    • Specifications (title, values)

    • Buy suggestion (count, percent)

    • Customer feedback (recommended %, advantages, disadvantages)

    • Available variants and price range

4. get_product_recommendations

Similar products and alternatives

  • Purpose: Find similar/related products

  • When to use: When a product is close but not exact match

  • Parameters:

    • product_id (int): Reference product ID

    • offset (int, optional): Specific recommendation type

  • Returns: Simplified product list with:

    • Available recommendation tabs (similar products, related categories)

    • Filtered marketable products only

    • Same fields as search_products

5. search_text_lenz

AI-powered semantic search

  • Purpose: Visual/descriptive product search

  • Best for: Clothing, accessories, wearables, shoes

  • Query format: 2-3 word descriptions (e.g., "red summer dress", "black running shoes")

  • Parameters:

    • query (string): Visual/descriptive query

    • page (int): Page number (default: 1)

  • Returns: Simplified product list plus:

    • is_text_lenz_eligible: Whether Text-Lenz was used

    • related_searches: Alternative search suggestions

    • Pagination metadata

Installation

# Install dependencies
uv sync

# Or add to existing project
uv add "mcp[cli]" httpx

Usage

Running the Server

STDIO Transport (for Claude Desktop, Cursor, etc.)

uv run python main.py

Testing with MCP Inspector

uv run mcp dev main.py

Integration with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "digikala": {
      "command": "/path/to/local/uv",
      "args": [
          "run",
          "--directory",
          "/path/to/digikala-mcp-server",
          "python",
          "main.py"
        ]
    }
  }
}

📋 Example Usage

Example 1: Complete Discovery Workflow

Find me the best gaming laptop under 50M Toomans

AI Agent Workflow:

  1. Call get_optimized_keywords_and_categories("لپتاپ") (Farsi - single word)

  2. Call get_optimized_keywords_and_categories("laptop") (English - single word)

  3. Use keyword-category pairs from step 1 in search_products:

    • Example: search_products(category_id=22, keyword="gaming laptop", price_max_tooman=50000000, sort=7)

    • Try multiple keywords: "laptop", "gaming laptop", etc. with same category_id

    • Set sort=7 (Highest Rated) or sort=5 (Best Selling)

  4. Review results, maybe try sort=3 (Price High to Low) for premium options

  5. Call get_product_details(product_id) for top 3 candidates

  6. Compare specifications, ratings, and customer feedback

Example 2: Iterative Search Refinement

I want noise-cancelling headphones for under 10M Toomans

AI Agent Workflow:

  1. Optimize: get_optimized_keywords_and_categories("هدفون") (single word)

  2. Optimize: get_optimized_keywords_and_categories("headphone") (single word)

  3. Get keyword-category pairs and search:

    • search_products(category_id=83, keyword="noise cancelling headphones", price_max_tooman=10000000)

  4. If too many results: Add sort=7 (Highest Rated)

  5. If too few results: Try different keywords or sort=5 (Best Selling) or increase price

  6. Review page 2-3 if needed with page=2

  7. Get details for promising products

Example 3: Visual/Descriptive Search

Find me a casual blue shirt for summer

AI Agent Workflow:

  1. Use search_text_lenz("blue casual shirt") - exceptional for clothing

  2. Review results and related searches

  3. Try variations: search_text_lenz("summer blue shirt")

  4. Get details for promising items

  5. Use get_product_recommendations to explore similar styles

Example 4: Finding Alternatives

I like this product but want to see similar options

AI Agent Workflow:

  1. Get current product: get_product_details(product_id)

  2. Get alternatives: get_product_recommendations(product_id)

  3. Review available recommendation tabs

  4. Try different offsets for category neighbors

  5. Get details for interesting alternatives

Development

Project Structure

digikala-mcp-server/
├── main.py              # MCP server implementation
├── tests.py             # Comprehensive test suite
├── pyproject.toml       # Project configuration
├── uv.lock             # Dependency lock file
└── README.md           # This file

Development Approach

This project follows a diffusion-inspired iterative development methodology:

  • Phase 1: Simple working core (query optimization + basic search)

  • Phase 2: Enhanced features (simplified outputs, bilingual support, integrated extraction)

  • Phase 3: Smart filtering (marketable products, star ratings, intelligent defaults)

  • Future: Error handling and production hardening

Key Design Decisions

  1. Simplified Outputs: All tools return parsed, clean data instead of raw API responses

  2. Marketable Products Only: Non-available products are filtered out automatically

  3. Smart Ratings: Star ratings (0-5) only shown when statistically significant (10+ reviews)

  4. Bilingual Support: Emphasis on searching with both Persian and English queries

  5. Integrated Extraction: Product extraction built into search tools, not separate

  6. Intelligent Defaults: Always filters for available stock (has_selling_stock=1)

Testing

Comprehensive Test Suite

Run the full test suite covering all refactored tools:

uv run python tests.py

The test suite validates:

  • ✅ Query optimization (bilingual support)

  • ✅ Simplified search results (marketable products only)

  • ✅ Rating conversion (stars from 0-5)

  • ✅ Pagination (20 items per page)

  • ✅ Filtering and sorting

  • ✅ Parsed product details

  • ✅ Simplified recommendations

  • ✅ Text-Lenz semantic search

  • ✅ Currency conversion (Tooman/Rial)

  • ✅ Edge cases and error handling

Features:

  • Built-in timeout protection (30s per HTTP request)

  • Proper error handling and cleanup

  • Validates all tool outputs are simplified/parsed

  • Exit codes for CI/CD integration

Direct Function Testing

Quick testing of individual functions:

from main import get_optimized_keywords_and_categories, search_products, get_product_details

# Test query optimization (single word queries)
optimized = get_optimized_keywords_and_categories("لپتاپ")
print(f"Optimized keywords: {optimized['optimized_queries']}")
print(f"Categories: {optimized['categories']}")

# Extract keyword-category pair
category_id = optimized['categories'][0]['id']  # e.g., 22
keyword = optimized['categories'][0]['query']   # e.g., "laptop"

# Test search with filters (returns simplified products directly)
results = search_products(
    category_id=category_id,  # REQUIRED - from optimization step
    keyword=keyword,          # REQUIRED - from optimization step
    price_min_tooman=1000000,   # 10M Rials
    price_max_tooman=10000000,  # 100M Rials
    sort=2,  # Price Low to High
)

# Results are already simplified
for product in results['products'][:3]:
    rating = f"{product['rating_stars']}⭐" if product['rating_stars'] else "No rating"
    print(f"{product['title_fa']}: {product['selling_price_tooman']:,} Toomans - {rating}")

# Get detailed info
details = get_product_details(results['products'][0]['id'])
print(f"Specs: {len(details['specifications'])} attributes")
print(f"Customer feedback: {details.get('customer_feedback', {})}")

API Documentation

This server integrates with:

  • Digikala Autocomplete API v1: https://api.digikala.com/v1/autocomplete/

  • Digikala Search API v2: https://api.digikala.com/v2/category/{category_id}/

  • Digikala Product Details API v2: https://api.digikala.com/v2/product/{id}/

  • Digikala Tabular Recommendations API v1: https://api.digikala.com/v1/product/{id}/tabular-recommendation/

  • Digikala Text-Lenz Search API v1: https://api.digikala.com/v1/search/text-lenz/

License

MIT

📊 Product Data Format

All tools return products in this simplified format:

{
    "id": 12345,
    "title_fa": "عنوان فارسی محصول",
    "title_en": "Product English Title",
    "url": "/product/dkp-12345/...",
    "selling_price_rial": 15250000,
    "selling_price_tooman": 1525000,
    "rrp_price_rial": 18000000,
    "rrp_price_tooman": 1800000,
    "discount_percent": 15,
    "rating_stars": 4.3,        # 0-5 scale, None if <10 reviews
    "rating_count": 156,
    "brand": "Samsung",
    "category": "[Mobile,موبایل]",
    "is_incredible": False,
    "is_digiplus_jet_eligible": True
}

Notes:

  • Only marketable products are returned (automatically filtered)

  • rating_stars is None if rating_count < 10 (not statistically significant)

  • Both Tooman and Rial prices always included

  • URL relative to digikala.com

Version

0.2.0 - Refactored with simplified outputs and intelligent discovery workflow

  • Integrated extraction into search tools

  • Bilingual search support

  • Smart rating conversion

  • Parsed/simplified all outputs

  • Intelligent filtering defaults

Available Tools

5 tools
get_optimized_keywords_and_categoriesGet optimized keywords and categoriesA
Read-only

Get optimized search keywords and relevant categories. IMPORTANT: Always call this with BOTH Persian (Farsi) and English queries separately, as the API responds differently to each language and Farsi typically yields better, more comprehensive results.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSingle word query to get optimized keywords and categories for. Must be only one word (e.g., 'laptop', 'shoe', 'phone')

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already indicate this is a read-only, non-destructive, open-world operation. The description adds valuable behavioral context: the API responds differently to Persian vs. English queries, with Farsi yielding better results. This language-specific behavior isn't covered by annotations, enhancing transparency about how the tool behaves in practice.

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 extremely concise and well-structured: one sentence stating the purpose, followed by a crucial usage instruction. Every word earns its place, with no redundancy or unnecessary information. The important guidance is appropriately emphasized with 'IMPORTANT:' and placed upfront.

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 has comprehensive annotations (readOnlyHint, openWorldHint), 100% schema coverage, and an output schema exists, the description provides excellent contextual completeness. It adds crucial language-specific usage guidance that wouldn't be captured in structured fields, making it complete for agent understanding despite the structured data richness.

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 fully documents the single 'query' parameter. The description doesn't add parameter-specific details beyond what's in the schema. However, it does imply language considerations (Persian/English) that relate to how the query parameter should be used, though not explicitly about the parameter itself.

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's purpose: 'Get optimized search keywords and relevant categories.' It specifies both the output (keywords and categories) and the optimization aspect. However, it doesn't explicitly differentiate from sibling tools like 'search_products' or 'search_text_lenz' which might also involve keywords or categories.

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?

The description provides explicit usage guidance: 'Always call this with BOTH Persian (Farsi) and English queries separately, as the API responds differently to each language and Farsi typically yields better, more comprehensive results.' This gives clear instructions on when and how to use the tool, including language-specific behavior and performance expectations.

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

get_product_detailsGet Product DetailsA
Read-onlyIdempotent

Get comprehensive product information including specifications, expert reviews, customer feedback, and buy suggestions. Use this when you need detailed information about a specific product.

ParametersJSON Schema
NameRequiredDescriptionDefault
product_idYesUnique product identifier

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds value by specifying the scope of information returned (specifications, reviews, feedback, buy suggestions) and the requirement for a specific product, which goes beyond what annotations convey about behavior.

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 sentences, front-loaded with the core purpose and followed by usage guidance. Every word earns its place, with no redundancy or fluff, making it highly efficient and easy to parse.

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 simplicity (1 parameter, 100% schema coverage), rich annotations (readOnly, openWorld, idempotent, non-destructive), and the presence of an output schema, the description is complete. It clearly states what the tool does and when to use it, which is sufficient for an agent to select and invoke it correctly in context.

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%, with the single parameter 'product_id' well-documented as a 'Unique product identifier'. The description doesn't add any additional parameter semantics beyond what the schema provides, such as format examples or constraints, so it meets the baseline for high schema coverage.

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 clearly states the action ('Get comprehensive product information') and resource ('product'), with specific details about what information is included (specifications, expert reviews, customer feedback, buy suggestions). It distinguishes from sibling tools like 'search_products' by focusing on detailed information for a specific product rather than searching or listing.

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 provides explicit guidance on when to use this tool ('when you need detailed information about a specific product'), which helps differentiate it from siblings like 'get_product_recommendations' or 'search_products'. However, it doesn't explicitly state when NOT to use it or name specific alternatives for edge cases.

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

get_product_recommendationsGet Product RecommendationsA
Read-onlyIdempotent

Get similar products and related category recommendations. Use this when a product is close but not exactly what you need, to explore similar alternatives.

ParametersJSON Schema
NameRequiredDescriptionDefault
product_idYesProduct ID for which recommendations are needed
offsetNoOptional recommendation tab/offset to retrieve specific recommendation type

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

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

The description adds valuable context beyond annotations by explaining the tool's purpose ('explore similar alternatives') and use case. Annotations already cover safety (readOnlyHint=true, destructiveHint=false) and reliability (idempotentHint=true, openWorldHint=true), so the bar is lower. The description doesn't add behavioral details like rate limits or auth needs, but provides useful application context.

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 perfectly concise with two sentences that each earn their place. The first states the purpose, the second provides usage guidance. No wasted words, and it's front-loaded with the core functionality.

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 moderate complexity, comprehensive annotations (covering safety and reliability), 100% schema coverage, and the presence of an output schema, the description is complete enough. It explains what the tool does and when to use it, which is sufficient since annotations handle behavioral traits and schemas handle inputs/outputs.

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?

With 100% schema description coverage, the schema already fully documents both parameters (product_id and offset). The description doesn't add any parameter-specific information beyond what's in the schema, so it meets the baseline of 3. It doesn't explain parameter interactions or provide additional semantic context.

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 clearly states the specific verb ('Get') and resource ('similar products and related category recommendations'), and distinguishes from siblings by specifying its unique use case ('when a product is close but not exactly what you need, to explore similar alternatives'). This differentiates it from tools like get_product_details (single product info) and search_products (general search).

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?

The description explicitly states when to use this tool ('when a product is close but not exactly what you need, to explore similar alternatives'), providing clear context for its application. While it doesn't name specific alternatives, it implicitly distinguishes from search_products (for general searches) and get_product_details (for single product info).

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

search_productsSearch ProductsA
Read-onlyIdempotent

Search for products within a specific category with filtering and sorting. Returns 20 products per page. CRITICAL WORKFLOW: ALWAYS call get_optimized_keywords_and_categories FIRST to get the category_id for your search - this API requires it. Use the keyword-category pairs from that response. Search with BOTH Persian (Farsi) and English keywords separately - they produce different results, with Farsi often being more comprehensive. All prices in TOOMAN (1 Tooman = 10 Rials).

ParametersJSON Schema
NameRequiredDescriptionDefault
category_idYesCategory ID to search within (REQUIRED - get this from get_optimized_keywords_and_categories)
keywordYesSearch keyword string for products, retrieved from the get_optimized_keywords_and_categories tool results
pageNoPage number (starts from 1)
sortNoSort order: 1=Relevance, 2=Price Low-High, 3=Price High-Low, 4=Newest, 5=Best Selling, 6=Most Viewed, 7=Highest Rated
price_min_toomanNoMinimum price in Toomans (e.g., 1000 Toomans = 10,000 Rials)
price_max_toomanNoMaximum price in Toomans (e.g., 5000 Toomans = 50,000 Rials)
discount_minNoMinimum discount percentage
discount_maxNoMaximum discount percentage
colorsNoList of color IDs to filter by

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior4/5

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

The description adds valuable behavioral context beyond annotations: it specifies pagination ('Returns 20 products per page'), currency details ('All prices in TOOMAN'), and language handling ('Farsi often being more comprehensive'). While annotations cover safety (readOnlyHint=true, destructiveHint=false), the description enriches operational understanding without contradiction.

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 well-structured and front-loaded with core functionality, followed by critical workflow instructions. Each sentence adds value (e.g., pagination, currency, language tips), though it could be slightly more concise by integrating some details into the schema.

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 (9 parameters, filtering/sorting), the description provides complete context: it explains prerequisites, workflow integration, language nuances, currency, and pagination. With annotations covering safety and an output schema presumably handling return values, no significant gaps remain.

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?

With 100% schema description coverage, the input schema already documents all 9 parameters thoroughly. The description adds minimal param-specific info (e.g., emphasizing category_id requirement and keyword usage), but most semantics are redundant. This meets the baseline for high schema coverage.

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 clearly states the tool's purpose: 'Search for products within a specific category with filtering and sorting.' It specifies the verb ('Search'), resource ('products'), and scope ('within a specific category'), distinguishing it from siblings like get_product_details (detail retrieval) and search_text_lenz (text-based search).

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?

The description provides explicit guidance on when and how to use this tool: 'ALWAYS call get_optimized_keywords_and_categories FIRST to get the category_id' and 'Search with BOTH Persian (Farsi) and English keywords separately.' It also mentions workflow integration and language-specific behavior, offering clear alternatives and prerequisites.

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

search_text_lenzSearch with Text-Lenz AIA
Read-onlyIdempotent

AI-powered semantic search using Text-Lenz. Exceptional for clothing, accessories, wearables, and shoes. Use 2-3 word visual descriptions (e.g., 'red summer dress', 'black running shoes'). Understands natural language and context.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesVisual/descriptive query (2-3 words work best, e.g., 'blue cotton shirt')
pageNoPage number for pagination (default: 1)

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare this as read-only, non-destructive, idempotent, and open-world. The description adds valuable behavioral context about the AI-powered semantic nature, domain specialization, and query format preferences (2-3 word visual descriptions), which goes beyond what 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?

Three tightly focused sentences with zero waste. The first establishes the core function, the second provides domain and usage guidance, and the third explains capabilities. Every sentence 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?

Given the tool has comprehensive annotations, 100% schema coverage, and an output schema exists, the description provides excellent contextual completeness. It explains the AI/semantic nature, domain specialization, and query approach that aren't captured in structured fields.

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 fully documents both parameters. The description reinforces the query format guidance ('2-3 word visual descriptions') but doesn't add significant semantic meaning beyond what's in the schema descriptions.

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 clearly states the tool performs 'AI-powered semantic search using Text-Lenz' with specific domain focus on 'clothing, accessories, wearables, and shoes'. It distinguishes from sibling tools like 'search_products' by emphasizing the AI/semantic nature and visual description approach.

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 guidance is provided on when to use this tool: 'Exceptional for clothing, accessories, wearables, and shoes' and 'Use 2-3 word visual descriptions'. The description also distinguishes this from other search approaches by noting it 'understands natural language and context'.

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.

  1. 5 tool updatesv0.1.0
    • First observedget_optimized_keywords_and_categories
    • First observedget_product_details
    • First observedget_product_recommendations
    • First observedsearch_products
    • First observedsearch_text_lenz
Deploy Server
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

TDQS

A4.3/5.0

Scored across 5 tools

Disambiguation4/5

The tools have mostly distinct purposes, with clear boundaries: get_optimized_keywords_and_categories for keyword/category optimization, get_product_details for detailed product info, get_product_recommendations for similar products, search_products for category-based searches, and search_text_lenz for semantic visual searches. However, search_products and search_text_lenz both involve searching, which could cause minor confusion, though their descriptions clarify different use cases (category-based vs. semantic/visual).

Naming Consistency4/5

Tool names follow a consistent verb_noun pattern with underscores (e.g., get_optimized_keywords_and_categories, search_products), making them predictable and readable. There is a minor deviation with search_text_lenz, which includes a brand name 'Text-Lenz' in the noun part, but it still fits the overall naming convention without mixing styles like camelCase.

Tool Count5/5

With 5 tools, this server is well-scoped for an e-commerce product search and information domain. Each tool serves a specific function (e.g., optimization, details, recommendations, searches), and none feel redundant or unnecessary, providing a balanced set for typical agent workflows in this context.

Completeness3/5

The tool set covers key operations like searching, getting details, and recommendations, but there are notable gaps. For example, there are no tools for user account management (e.g., login, cart operations), purchase-related actions (e.g., add to cart, checkout), or content management (e.g., reviews, ratings). While the domain appears focused on product discovery and information, these omissions could limit agent functionality in full e-commerce scenarios.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers