zoomit-mcp

Overview Schema Source Related Servers Discussions Admin

Rank products by a spec or value

zm_rank

Read-onlyIdempotent

Ranks popular products in a category by one numeric spec or value for money, with filters for price, brand, and score to surface suitable matches.

Instructions

Rank a category's popular products by one numeric spec (battery, weight, RAM, brightness) or by value for money.

Use for "phone with the biggest battery under 30 million" or "best value laptop". Only the candidates most popular matches are ranked, so narrow the filters rather than raising it. Storage is normalised to GB.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "category": "<category>",
      "by": "<by>"
    },
    "name": "zm_rank"
  }
}

Input Schema

Name	Required	Description	Default
`by`	Yes	Spec to rank by (part of its Persian name, e.g. ظرفیت باتری, وزن) or 'value' for user score per million Toman.
`limit`	No	Max ranked products.
`order`	No	high = biggest first.	high
`query`	No	Same as zm_list.
`specs`	No	Same as zm_list.
`brands`	No	Brand slugs from zm_filters.
`category`	Yes	Category slug from zm_categories, e.g. mobile, laptop, vga.
`max_price`	No	Highest price in Toman.
`min_price`	No	Lowest price in Toman.
`min_score`	No	Min user score, whole stars.
`candidates`	No	Most popular matches to rank (one request per 4).

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.0Nov 6, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), so the description correctly spends its words elsewhere: it discloses the significant limitation that only the top `candidates` popular matches are ranked, and that storage values are normalised to GB before comparison. It adds context beyond the annotations rather than repeating them; it does not mention the cost hint present in the `candidates` parameter description ('one request per 4').

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?

Two short paragraphs: purpose plus examples first, then the operative constraint about candidate truncation. No restated field descriptions, no filler, and the limitation is placed after the purpose where an agent will still read it.

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 an 11-parameter ranking tool with no output schema, the description covers the two things an agent cannot get from the schema alone: that results are popularity-truncated and that spec values are unit-normalised. It does not state the shape of the returned ranking (position, the ranked metric value), which is the remaining gap given the absence of an output schema.

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 earns a bump by explaining the practical meaning of `candidates` — the ranking population is truncated to the most popular matches — and by flagging the GB normalisation that affects how spec strings like ظرفیت باتری are compared. It still defers to the schema for `by`, `order`, and the price/score filters.

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 first sentence names a specific verb and resource: 'Rank a category's popular products by one numeric spec ... or by value for money,' and the examples ('phone with the biggest battery under 30 million', 'best value laptop') confirm the semantics. It does not explicitly differentiate itself from siblings like zm_list or zm_compare, so an agent must infer that this is a ranking layer on top of the filtered list.

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 two quoted example queries make the intended use case concrete, and 'Only the `candidates` most popular matches are ranked, so narrow the filters rather than raising it' is real operating guidance about tuning filters instead of widening the candidate pool. It stops short of naming when to prefer zm_list or zm_compare over zm_rank.

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

Deploy Server