An MCP server that lets AI agents (Claude Desktop, Hermes Agent, Cursor, OpenCode, …) search Ukrainian marketplaces — OLX, Hotline.ua, Prom.ua and Rozetka — from a plain-language prompt and get back structured offers with links.
Status: alpha. OLX, Hotline and Prom work out of the box (no tokens); Rozetka is covered through the optional Bright Data MCP server (free tier: 5 000 requests/month). Verified with MCP Inspector and a real agent (OpenCode), including a 4-marketplace price comparison from a single prompt.
Ask in natural language:
"SSD 120–560 GB, 2.5", used, up to 1500 UAH"
and get a structured list of matching offers — title, price, location, link — instead of a wall of search results.
Related MCP server: OLX MCP Server
Built-in web search | This MCP server | |
Structured filters (price, form factor, condition) | guesswork | exact API filters |
Uniform, comparable result list | no | yes |
Repeatable / schedulable queries | no | yes |
Fresh marketplace listings | often stale | live |
For one-off lookups the difference is small; for structured comparison and monitoring it is the point.
natural-language prompt
│
▼
LLM (OpenCode / Hermes / Claude) ── maps prompt → tool arguments
│
▼
MCP tools ── search, filters, details, references
│
▼
Marketplace providers ── OLX (JSON API), Hotline / Prom (SSR), Rozetka (Bright Data MCP)
│
▼
structured offers (title, price, location, url)The server exposes these MCP tools (OLX / Hotline / Prom — registered out of the box):
search_offers(query, min_price, max_price, region_id, city_id, category_id, state, filters, limit, offset, include_promoted, sort)
— one page of offers plus the total match count. Category-specific attributes go into
filters as {"key": "value"} (choice) or {"key": [from, to]} (range).
sort: newest (server-side), price_asc/price_desc (sorts the returned page).
Promoted listings are excluded unless include_promoted=True.
get_offer_details(offer_id) — full listing: plain-text description, characteristics,
photo URLs, seller, status, dates.
list_filters(query, category_id) — discovers which category-specific filters exist
for a query (keys + sample values). Call before search_offers when an attribute is mentioned.
category_id restricts the sample to one category (broad queries otherwise mix categories).
list_categories() — curated category id/name list (static snapshot; OLX deprecated
the live category endpoint).
list_regions() — OLX region (oblast) and major city ids.
hotline_search_offers(query, min_price, max_price, limit, offset) — Hotline product
models (new items from shops) with the minimum shop price.
prom_search_offers(query, min_price, max_price, limit, offset) — Prom products
(new items from shops).
Rozetka has no tool in this server — it is queried through the Bright Data MCP browser tools (see Optional: Bright Data MCP). The server's instructions tell the agent to do so automatically for price comparisons.
Find me an SSD 120–560 GB, 2.5", used, up to 1500 UAH on OLX
Cheap used monitors in Kyiv up to 2000 UAH, show the 5 cheapest
Details of offer 931436822
The agent maps these onto the tools: it calls list_filters to learn valid filter keys,
list_regions/list_categories for ids, then search_offers with the narrowed arguments.
Server-side instructions tell it to report only filters actually used and to format the
result as a list with prices and links.
pip install marketua # or: uvx marketua (no install needed)
marketua # runs the MCP server over stdio (a client spawns it)For development from this repo:
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest -q # testsAny MCP client works. OpenCode:
// opencode.json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"marketua": {
"type": "local",
"command": ["uvx", "marketua"],
"enabled": true
},
// Rozetka (and any JS-rendered / Cloudflare-protected site) goes through
// the Bright Data MCP — free tier: 5 000 requests/month. Token from
// Bright Data → Settings → API Tokens (see .env.example in this repo).
"brightdata": {
"type": "remote",
"url": "https://mcp.brightdata.com/mcp?token={env:BRIGHT_DATA_API_KEY}&tools=scrape_as_markdown,scrape_as_html,search_engine&groups=browser",
"enabled": true
}
}
}If the client can't find uvx: GUI apps (VS Code, Claude Desktop, Cursor) often don't inherit your shell's PATH, so a freshly installed uv (in ~/.local/bin) may be invisible to them. Find the path with which uvx and put it in command, or skip uvx entirely: pip install marketua and use marketua as the command.
Optional env vars. The server reads MARKETUA_DISABLE_PROVIDERS (comma-separated:
olx, hotline, prom) from its own environment to disable marketplaces. Most MCP clients
(Claude Desktop, Cursor — see below) forward a per-server env block from the config;
OpenCode does not forward env to spawned local MCP servers, so for OpenCode export the
variable in the shell before launching it.
Then ask e.g. "Find me a used monitor up to 2000 UAH". The model picks the right tool
itself: marketua_* for OLX / Hotline / Prom (free), brightdata_* for Rozetka and other
hard-to-reach sites.
Rozetka is a Cloudflare-protected Angular SPA — it needs a real browser, so it goes through Bright Data's official MCP server. It is optional: without it the agent searches OLX / Hotline / Prom and says Rozetka was skipped; with it, price comparisons cover all four marketplaces.
Free tier: 5 000 requests/month, no credit card. Token: Bright Data → Settings → API Tokens (not the proxy credential). The agent spends ~2–4 requests per search (navigate + snapshot + get_text).
Data lives only in your chat — nothing is stored by us.
Claude Desktop (claude_desktop_config.json). The env block is optional —
include it only to disable marketplaces (comma-separated: olx, hotline, prom):
{
"mcpServers": {
"marketua": {
"command": "uvx",
"args": ["marketua"],
"env": {
"MARKETUA_DISABLE_PROVIDERS": "prom"
}
},
"brightdata": {
"url": "https://mcp.brightdata.com/mcp?token=YOUR_TOKEN&tools=scrape_as_markdown,scrape_as_html,search_engine&groups=browser"
}
}
}Cursor (~/.cursor/mcp.json) — same optional env block for disabling marketplaces:
{
"mcpServers": {
"marketua": {
"command": "uvx",
"args": ["marketua"],
"env": {
"MARKETUA_DISABLE_PROVIDERS": "prom"
}
},
"brightdata": {
"url": "https://mcp.brightdata.com/mcp?token=YOUR_TOKEN&tools=scrape_as_markdown,scrape_as_html,search_engine&groups=browser"
}
}
}For manual verification of every tool, use MCP Inspector:
npx @modelcontextprotocol/inspector --web uvx marketuaMarketplace | Status | Data source | Cost |
OLX.ua | MVP (alpha) | public JSON API ( | free |
Hotline.ua | MVP (alpha) | SSR search page | free |
Prom.ua | MVP (alpha) | SSR search (embedded JSON-LD) | free |
Rozetka.ua | via Bright Data MCP | remote browser (JS-rendered site) | free tier: 5 000 req/mo |
One stable interface, many providers:
MCP layer (tools) → Provider interface → [OLXProvider, HotlineProvider, PromProvider]
(Rozetka — via the Bright Data MCP, no provider)MCP transport: stdio (simplest, the client spawns it as a child process). No hosted
server — shipped as a Python package (pip install marketua / uvx marketua), so each
user runs their own local instance.
Provider interface keeps marketplace specifics behind one abstraction, so adding a platform never touches the agent-facing layer.
OLX category ids are a static snapshot (the live category endpoint is deprecated); the server detects stale ids at query time and warns instead of silently returning wrong results.
Credentials (e.g. the Bright Data token) are configured by you in your client or shell, never committed.
MIT. This project is educational. It uses only public, unauthenticated data and respects
robots.txt and rate limits. Marketplace ToS may restrict automated access — use
responsibly, keep request rates low, and do not redistribute data at scale or bypass any
access controls. The optional Bright Data MCP is a third-party service with its own ToS and
free-tier limits.
Get full details for one OLX offer by id: plain-text description, characteristics, photo URLs, seller, status and dates.
| Name | Required | Description | Default |
|---|---|---|---|
| offer_id | Yes | OLX offer id — the 'id' field of a search_offers result, e.g. '929558300'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It discloses the tool provides multiple types of data (text, photos, seller info) and implies a read-only operation. However, it doesn't specify return format limits (e.g., max photo URLs, pagination of characteristics), auth requirements, or whether the offer must be active/visible. Lacks full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the key action and lists contents efficiently. It earns its place without extraneous words. Could be improved by slightly greater precision on what constitutes 'full details' but is very clear overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only one parameter, no nested objects, high schema coverage, and no output schema, the description is reasonably complete. It explains what data is returned (text, photos, seller, etc.) and how to use the parameter. Without an output schema, it would benefit from mentioning return structure, but the context signals reduce that need.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and already describes the offer_id parameter well, including format and example. The description adds value by confirming the id comes from search_offers results, but doesn't add semantic details beyond the schema. Baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves full details for a single OLX offer by ID, listing specific content (plain-text description, characteristics, photo URLs, seller, status, dates). This is a specific verb+resource combination that distinguishes it from sibling tools like search_offers, which returns multiple results rather than one item's complete details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need comprehensive information for a particular offer, contrasting with search_offers which returns a list. It states the required input is an offer_id obtained from search_offers results, giving clear context for when to use this tool vs alternatives, though it does not explicitly say when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Hotline.ua (Ukrainian price aggregator) and return matching product models with their price range across shops. Returns {'total', 'returned', 'offers'}; each offer has id, title, price (minimum shop price, UAH), currency, url. NOTE: Hotline returns product MODELS, not individual listings — price is a range, and location is not available in search results. Use for comparing prices/specs of a product model. For used/individual listings (with location), also call search_offers (OLX).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of products to return (default 20). | |
| query | Yes | Search keywords, e.g. 'ssd 2.5 sata' or 'монітор 24'. | |
| offset | No | Pagination: skip the first N matches (default 0). | |
| max_price | No | Maximum product price in UAH (applied to the min shop price). Omit for no upper bound. | |
| min_price | No | Minimum product price in UAH (applied to the min shop price). Omit for no lower bound. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility. It discloses critical behavior: returns product MODELS not individual listings, price is a range, location unavailable. It does not mention rate limits or authentication requirements, but for a search tool these are typically less critical. The note about price being minimum shop price adds transparency beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero wordiness. The first sentence immediately states purpose and return format. The second adds the crucial behavioral note. The third provides usage guidance and sibling differentiation. Information is front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 5 parameters, the description explains the return structure ({total, returned, offers}; each offer has id, title, price, currency, url), explains what price means (min shop price, UAH), and covers limitations (model-level, no location). It also references sibling tools. Pagination is covered by schema, but the description is self-sufficient for an agent to understand inputs, outputs, and context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that price represents minimum shop price in UAH, gives query examples like 'ssd 2.5 sata' or 'монітор 24', and clarifies that min/max price is 'applied to the min shop price'. This interpretation helps the agent understand parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'Search' and resource 'Hotline.ua (Ukrainian price aggregator)', clearly stating it returns 'product models with their price range across shops'. It explicitly differentiates from sibling tool search_offers (OLX) by noting Hotline returns models, not individual listings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance: use for 'comparing prices/specs of a product model' and advises to also call search_offers (OLX) 'for used/individual listings (with location)'. This creates a clear when-to-use and when-not-to-use directive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List OLX categories (id + name) so you can look up a category_id to pass to search_offers. Static snapshot of the most useful categories — the live OLX category endpoint is deprecated. Omit category_id in search_offers when the category is not listed here.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the data is a static snapshot of the most useful categories and that the live OLX category endpoint is deprecated. This gives important behavioral context about data freshness and completeness, which goes beyond a simple 'list' command.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the action and purpose, and every word adds value. There is no repetition or irrelevant information, making it highly efficient for an AI agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description sufficiently explains the return format (id and name), the tool's limitation (static snapshot), and its practical use (feeding category_id to search_offers). For a zero-parameter tool, this level of detail is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so baseline is 4. The description adds value by clarifying the output structure (id and name) and the static nature of the list, which supplements the empty schema adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists OLX categories with id and name for the purpose of obtaining a category_id to use with search_offers. It distinguishes itself from siblings by specifying its unique output and relationship to search_offers, making it easy for an agent to select this tool over list_filters or list_regions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 (before search_offers to get a category_id) and when to omit category_id in search_offers (if the category is not listed). However, it does not explicitly exclude usage for other scenarios or compare to sibling tools like list_filters, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover which category-specific filter attributes (and sample values) exist for a search query. Call this BEFORE search_offers when the user mentions an attribute like resolution, capacity, brand, etc., so you can pass valid keys in filters. If the query could match several categories (e.g. 'ssd' also hits laptops), pass category_id from list_categories() to sample only that category.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many offers to sample (1..50, default 40). | |
| query | Yes | Search phrase to inspect, e.g. 'монітор' or 'ssd'. | |
| category_id | No | OLX category id from list_categories() to restrict the sample to one category. Omit for keyword-wide discovery. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits: the tool samples offers to extract filter attributes, it requires a query string, and it can be scoped to a category. Since no annotations are provided, the description carries full burden for transparency. It covers intent well but doesn't mention limitations like sample size or missing filters if category is not specified. Still, given no annotations, this is strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that pack purpose, usage timing, and an edge case example. Every sentence earns its place with actionable information, and it front-loads the purpose without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 3 parameters (one required), an output schema (which the description doesn't need to cover), and no annotations, the description is remarkably complete. It tells the agent when to use it, how to handle ambiguous queries, and what to expect as output (filter attributes with sample values). No gaps are apparent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. However, the description adds meaning by explaining how parameters relate to the workflow (e.g., query should be 'монітор' or 'ssd', category_id comes from list_categories(), limit is for sampling). It doesn't add new param descriptions but enriches the context of usage, justifying a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('Discover', 'find') and a clear resource ('category-specific filter attributes and sample values for a search query'). It explicitly distinguishes this tool from siblings by positioning it as a prerequisite to search_offers, which is listed as a sibling. This makes the purpose unambiguous and well-differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to call this tool: 'BEFORE search_offers when the user mentions an attribute like resolution, capacity, brand, etc.' It also explains the alternative behavior for ambiguous queries ('pass category_id from list_categories() to restrict to one category'). This is a perfect example of usage context with exclusions and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List OLX regions (oblasts) and major cities with their ids, for search_offers region_id/city_id.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It discloses the tool lists regions/cities with ids – a safe read operation. No mention of performance, caching, or region scope, but adequate for a simple lookup.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. Front-loaded with action and resource, and includes purpose context (ids for search_offers).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero params and no output schema, the description is nearly complete. It could mention whether cities are grouped under regions or are flat, but the core need (getting ids for search_offers) is met.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has zero parameters and coverage is 100%, so no param info needed. Description adds value by explaining the output ties to search_offers parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states specific verb (List), resource (OLX regions and major cities), and output (ids for search_offers). Distinguishes from siblings like search_offers (which uses the ids) and list_categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear context for use – provides ids needed by search_offers. No explicit when-not or exclusions, but sibling tool names hint at alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Prom.ua (Ukrainian B2C marketplace) and return matching products. Returns 'total', 'returned', 'offers'}; each offer has id, title, price (UAH), currency, url. Prom sells new products from shops (like Hotline). For used/individual listings use search_offers (OLX).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of products to return (default 20). | |
| query | Yes | Search keywords, e.g. 'ssd 2.5' or 'холодильник'. | |
| offset | No | Pagination: skip the first N matches (default 0). | |
| max_price | No | Maximum product price in UAH. Omit for no upper bound. | |
| min_price | No | Minimum product price in UAH. Omit for no lower bound. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions the return structure (total, returned, offers with fields) but does not explicitly state that the operation is read-only or idempotent. It also omits authentication requirements or rate limits. For a search tool, the behavioral implications are mostly clear, but explicit safety disclosure would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a usage tip—concise and front-loaded with the action and return structure. Every sentence adds value, and there is no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description usefully lists the return fields (total, returned, offers with id, title, price, currency, url). It also covers marketplace context and sibling differentiation. With 100% schema coverage, the description is sufficient for an agent to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%—all parameters already have descriptions in the schema. The description adds minimal value beyond the schema, only clarifying that price is in UAH (already stated in schema). The baseline is 3 for high coverage, and the description does not significantly enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool searches Prom.ua (Ukrainian B2C marketplace) and returns matching products. It differentiates from the sibling 'search_offers' by specifying that Prom sells new products from shops, while the other is for used/individual listings. The verb 'Search' and resource 'Prom.ua' are clear and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 versus alternatives: 'For used/individual listings use search_offers (OLX).' It also gives context that Prom sells new products and compares it to Hotline, helping the agent decide when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search OLX.ua (Ukrainian classified ads) and return a page of matching offers plus the total count. Returns {'total', 'returned', 'offers'}; each offer has id, title, price (UAH), currency, location, url. For category-specific attributes (brand, resolution, capacity, ...) call list_filters(query) FIRST, then pass the keys via filters. For region/city ids call list_regions(); for a category id call list_categories(). For comparing prices of a new product across shops, also call hotline_search_offers and prom_search_offers. For Rozetka, use the brightdata MCP server's browser tools.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Result ordering: 'newest' = by creation date, newest first (server-side, OLX supports it); 'price_asc' / 'price_desc' = cheapest / most expensive first (sorts the returned page client-side — OLX ignores server-side price sort). Omit for OLX default relevance order. | |
| limit | No | Maximum number of offers to return (1..50, default 20). | |
| query | Yes | Search keywords. Put attributes that have no dedicated filter (form-factor, brand, size) here as plain words, e.g. 'ssd 240gb 2.5' or 'диван б/у'. | |
| state | No | Condition filter: 'used' (б/у / вживане) or 'new' (нове). Omit to include both. | |
| offset | No | Pagination: skip the first N matches (default 0). Prefer narrowing with filters over deep pagination. | |
| city_id | No | OLX city id from list_regions(). Omit to search the whole region/country. | |
| filters | No | Category-specific filters; keys and values come from list_filters(query). Values are either a plain string (the option's key, e.g. {'resolution': 'full_hd'}) or a plain two-number list [from, to] for ranges (e.g. {'screen_size': [24, 24]}). The server also accepts the OLX-style {'item': [from, to]} wrapper for ranges. Omit keys you don't need. | |
| max_price | No | Maximum price in UAH (inclusive). Omit for no upper bound. | |
| min_price | No | Minimum price in UAH (inclusive). Omit for no lower bound. | |
| region_id | No | OLX region (oblast) id from list_regions(). Omit to search all of Ukraine. | |
| category_id | No | OLX category id from list_categories(). Narrows to one category. Omit for keyword search. | |
| include_promoted | No | Include paid/promoted listings (top_ad, highlighted, urgent). Default False (excluded). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavior: return format (total, returned, offers), offer structure (id, title, price in UAH, currency, location, url), sorting behavior (price_asc/price_desc sorted client-side), filters handling (string keys or two-number arrays for ranges), and the include_promoted option. It also notes that the server accepts OLX-style wrappers for range filters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a one-sentence purpose and return format summary, followed by a clear paragraph of usage guidelines. Every sentence adds unique value, no repetition of schema or annotations, and the structure front-loads the essential purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 12 parameters, no output schema, and no annotations, the description is remarkably complete. It covers the return format, offer fields, parameter usage patterns (query vs filters, location/category IDs), sorting behaviors, and platform alternatives. The description fully compensates for the lack of structured annotations and output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While schema coverage is 100%, the description adds significant meaning beyond the schema: it explains how to use the query parameter for attributes without dedicated filters, clarifies the client-side sorting behavior for price sorts, details the filter value format (string or two-number list) and the accepted OLX wrapper, and specifies that include_promoted controls top_ad, highlighted, and urgent listings. This goes well beyond the schema's field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches OLX.ua and returns a page of matching offers plus total count. It specifies the return format and distinguishes from sibling tools (hotline_search_offers, prom_search_offers, list_filters, etc.) by naming them explicitly, making the tool's specific function unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: call list_filters for category-specific attributes, list_regions for location IDs, list_categories for category IDs. It also tells the agent when to use alternatives (hotline_search_offers and prom_search_offers for price comparison across shops) and warns against deep pagination in favor of filters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.0.1get_offer_detailshotline_search_offerslist_categorieslist_filterslist_regionsprom_search_offerssearch_offersThe three search tools (search_offers, hotline_search_offers, prom_search_offers) are differentiated by platform (OLX, Hotline, Prom), which helps, but their descriptions overlap significantly—all return offers with similar fields. The guidance about when to call which is helpful but adds complexity. The other tools (get_offer_details, list_filters, list_categories, list_regions) are clearly distinct.
All tool names follow a consistent verb_noun pattern (e.g., search_offers, hotline_search_offers, get_offer_details, list_filters). The pattern is uniform and predictable, making it easy for an agent to infer functionality from the name.
With 7 tools covering search across three platforms, details retrieval, and lookup utilities (categories, regions, filters), the number is well-scoped. Each tool serves a clear purpose without being excessive or insufficient for the domain of Ukrainian classified/marketplace searches.
The tool set provides a solid core for searching across multiple Ukrainian marketplaces, retrieving details, and exploring filters. Missing features include user account actions (posting, deleting offers) and cross-platform price comparison aggregation, but the stated focus is search, so these gaps are minor.
Search ~8.5M products from 2,500+ Central European e-shops. Semantic, keyword, GTIN lookup.
AI shopping comparison — search 50M+ products, compare prices, find deals
Search the plati.market (Digiseller) catalogue and fetch product details with seller info.
Search products, compare prices and discover deals across 6 European markets with your AI assistant.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/cuzin85/marketua'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
