Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@oskelly-mcp search for women's jackets under 5000 rubles"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for the public catalog of oskelly.ru. 14 tools, anonymous read-only operations only, all verified against the live site.
Unofficial project, not affiliated with Oskelly. Reads exactly what any visitor without registration sees. Trademarks belong to their respective owners.
Related MCP server: VkusVill MCP Server
Node.js 22+.
git clone https://github.com/ihavealotofguap/oskelly-mcp.git
cd oskelly-mcp
npm ci
npm run build
npm run verifyClaude Desktop — claude_desktop_config.json (Settings → Developer → Edit Config), the path must be absolute:
{ "mcpServers": { "oskelly": { "command": "node", "args": ["/abs/path/oskelly-mcp/dist/index.js"] } } }spawn node ENOENT on Windows → replace "node" with the output of where node, escape the slashes.
After editing, fully restart the app, including the tray icon.
Claude Code — claude mcp add oskelly -- node /abs/path/oskelly-mcp/dist/index.js
Debugging — npm run inspector
Tool | What it does |
| Cheat sheet for the filter model: codes, formats, how to resolve a name into an id |
| Search: query, facets, price, boolean tags, pagination, sorting |
| Same query, but returns counts and available facets instead of products |
| Values of a single facet with ids ( |
| Query autocomplete |
| Category tree, trimmed by |
| Brands with ids, substring search, pagination |
| Product conditions with descriptions |
| Attribute dictionary (material, color, …) |
| Product card by id or URL: description, attributes, sizes, photos, seller |
| Seller's products |
| What actually exists in the seller's assortment |
| Homepage banners (FEMALE/MALE/KIDS/LIFESTYLE) |
| Expands a banner collection into a filter preset + products |
Flow: describe_filters → list_brands/category_tree/filter_values → search_products → get_product.
There is and can be no login, cookies, cart, favorites, messages, or orders. This is a property of the code:
credentials: "omit", no Authorization/Cookie headers.
POST is allowed only for three read-only search endpoints — the allow-list assertReadOnlyPost in src/client.ts.
All tools: readOnlyHint: true, destructiveHint: false.
A smoke test verifies that the tools list contains no names with login/cart/favourite/order/checkout/message/account.
The product card is parsed from __NUXT_DATA__. There is no public JSON endpoint for a single
product (GET /api/v2/products/{id} → 404), the page is rendered by Nuxt 3 on the server. The payload
is decoded with the official devalue package — the same
library Nuxt uses to serialize it; custom types are wired in through the standard revivers
(src/nuxt.ts). Not Playwright: ~150 MB of Chromium and 3–5 s versus a single GET in ~150 ms.
The slug in the URL is ignored — only the numeric id at the end matters, the tool accepts both.
Filter format in the /products/search* body: multi-select is an array of ids ({"brand": [675]}),
boolean is a bare boolean ({"sale": true}), price is an object ({"price": {"lower": 50000}}).
{"brand": "675"} and {"sale": [true]} are silently ignored, {"price": [a, b]} yields success: false.
Price is filtered by the size-SKU, not by the card price — a product can appear in results with a card
price below the boundary, so every response carries sizePriceRange: {min, max}.
Upstream counters are renamed: totalAmount → totalMatches, itemsCount → itemsOnPage.
Segments (baseCategory) are tree node ids: Women=2, Men=105, Kids=188, Lifestyle=366.
WAF: Cyrillic in the query must be percent-encoded, otherwise 403.
Context: raw responses are huge (the tree is ~1 MB, brands ~750 KB), so a compact
projection is returned by default; verbose: true returns the untouched response.
npm run verify # офлайн: сервер стартует, 14 tools, все read-only
node smoke-test.mjs # живой end-to-end по MCP против oskelly.ruThe smoke test launches the compiled server as a separate process over stdio and exercises every tool
against the live site — no mocks. Parameters are chained from previous responses
(brand → search → productId → sellerId → banner), and each call passes a meaningful check:
PRICE_DESC really yields descending prices, conditionIds: [1] really yields only condition 1,
filters narrow the results monotonically. The latest run is SMOKE-TEST-OUTPUT.txt
(23 calls, 14/14 tools, 0 failures).
CI builds the project on Node 22/24/26 and runs npm run verify. The live smoke test is moved to a manual
run (Actions → CI → Run workflow → run_smoke_test) so as not to hammer a third-party site from runners.
src/client.ts HTTP-клиент, конверт, allow-list на POST
src/nuxt.ts извлечение и декодирование SSR-payload (devalue)
src/search.ts схема и сборка тела запроса для /products/search*
src/format.ts компактные проекции ответов
src/tools.ts определения 14 инструментов
src/index.ts точка входа, stdio-транспорт
scripts/verify-server.mjs офлайн-проверка поверхности tools (CI)
smoke-test.mjs живой end-to-end тест по протоколу MCPPRs are welcome. Before submitting — npm run build, npm run verify, node smoke-test.mjs.
The most fragile spots if oskelly updates: the __NUXT_DATA__ format (it will fail with an explicit error
pointing to adding a reviver in src/nuxt.ts), facet codes, segment ids. Rate-limiting
has not been tested; 45 s timeout, no retries — deliberately.
Open an oskelly.ru curated-selection page (a banner's catalogLink, e.g. https://oskelly.ru/catalog/bannerV2/) and return its title, the filter preset it encodes (for example a specific seller's wardrobe), the total item count and the first page of products. Curated pages are rendered server-side, so this reads the page's Nuxt payload rather than an API endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
| verbose | No | Return the raw upstream payload instead of the compact projection. Much larger. | |
| catalogLink | Yes | Full catalogLink URL or path from oskelly_home_banners, e.g. https://oskelly.ru/catalog/bannerV2/b9766c43-ebe5-4a7a-8597-8d6294a2a055 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is established. The description adds that it reads the Nuxt payload rather than an API endpoint, which is important behavioral context about how it works. It also mentions the verbose flag for raw payloads. No contradictions.
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, front-loaded with the action and return values, then explains the technical method. There is no fluff, every sentence contributes essential information. Efficient and clear.
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?
For a tool with two parameters, one required, and no output schema, the description covers the essential aspects: what it does, how it works (Nuxt payload), and the source of the input (catalogLink from banners). It doesn't detail pagination or total count semantics, but with no output schema expected, this is sufficient for an agent to invoke 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%, so the schema already documents both parameters thoroughly. The description adds that catalogLink comes from oskelly_home_banners, which is helpful context, but it doesn't add meaning beyond the schema's own parameter descriptions. Baseline 3 is appropriate given full 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 opens a curated-selection page via a banner's catalogLink and returns its title, filter preset, total item count, and first page of products. It uses a specific verb ('resolve') and resource ('curated selection'), and distinguishes it from API-based tools by noting it reads the Nuxt payload. This differentiates it from sibling tools like oskelly_search_products.
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 explains the tool is for curated pages from oskelly.ru banners, specifically when you have a catalogLink (e.g., from oskelly_home_banners). It implies when to use it (when dealing with banner links) and gives context that it uses server-side rendering. It doesn't explicitly state when not to use it, but the context is clear enough for an agent to select it correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the oskelly.ru category tree. The root (id 1, 'Каталог') has the four top-level segments as children — their ids are real tree node ids read from the live tree, not a fixed enum. Use rootId to zoom into a subtree and depth to control how many levels come back (the full tree is ~618 nodes / 1 MB, so keep depth small). Category ids from here feed oskelly_search_products categoryIds and baseCategory.
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | How many levels of children to include below rootId. | |
| rootId | No | Node id to start from. 1 = Каталог (root). Use a segment id to zoom in. | |
| verbose | No | Return the raw upstream payload instead of the compact projection. Much larger. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is known. The description adds valuable behavioral context: ids are live tree node ids rather than a fixed enum, the full tree size/payload is significant, and a compact projection is returned by default.
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, front-loaded with the core purpose, and every sentence earns its place: what it returns, how to control scope, and how the output is consumed downstream. No filler or repetition.
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?
For a simple read-only tree tool with no output schema, the description is largely complete: it explains the root, top-level children, dynamic ids, depth control, payload size, and downstream consumers. It does not describe the exact node shape of the returned tree, but the compact-vs-raw distinction and downstream usage compensate.
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 input schema already covers all 3 parameters with descriptions, so the baseline is 3. The description adds meaning by explaining that rootId id 1 is the catalog root, that top-level segment ids are dynamic real node ids, and that depth should be kept small because the full tree is ~618 nodes / 1 MB, which supplements the schema's parameter docs.
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 states a specific action ('Return the oskelly.ru category tree') and clearly identifies the resource and scope, including the root node and four top-level segments. It also distinguishes this tool from siblings by tying it to category id feeding for oskelly_search_products.
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 practical usage guidance: use rootId to zoom into a subtree, keep depth small due to the ~618-node/1MB full tree, and use returned ids as inputs to oskelly_search_products. It does not explicitly contrast with sibling tools, but the intended context and downstream use are clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a cheat-sheet of every filter code this server understands, how values are encoded, and which tool resolves names to ids. Call this once at the start of a browsing session instead of guessing filter names.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds useful behavior beyond that, such as the fact it returns a reference cheat-sheet and that it mentions the tool that resolves names to IDs, which helps the agent understand the tool's role without contradicting annotations.
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 succinct, consisting of two sentences that front-load what the tool returns and when to use it. There is no redundant or extra content.
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?
For a zero-parameter tool with no output schema, the description fully covers its content (filter codes, value encoding, name-to-id tool) and usage advice. It's complete and self-sufficient.
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?
There are zero parameters, so the schema is empty and the description doesn't need to add parameter explanations. The baseline of 4 for zero-parameter tools applies, and the description doesn't miss any parameter-related information.
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 returns a cheat-sheet of filter codes, value encoding, and which tool resolves IDs. This is a specific action on a well-defined resource, and it distinguishes from siblings like oskelly_filter_values by focusing on codes and encoding rather than values themselves.
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 says to call it once at the start of a browsing session instead of guessing filter names, providing clear timing and an anti-pattern. While it doesn't explicitly name alternative tools, it guides usage effectively.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the selectable values (with their ids) of a single facet, scoped to the same search context. This is how you resolve a human name to the numeric id that oskelly_search_products expects — e.g. code='brand' to find the id of GUCCI, code='size' to find size value ids for the current category. Accepts every search parameter so the returned values reflect the narrowed result set.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | Facet to enumerate: brand | category | size | condition | collection | model | sellerType | boutiqueLocationTag | |
| page | No | 1-based page number. | |
| limit | No | Maximum number of values to return (the brand facet has thousands). | |
| price | No | Price range in RUB; at least one of lower/upper must be set. NOTE (verified live): the backend matches this per size/SKU, not against the card price. A product matches if ANY of its sizes is priced inside the range, and the returned card `price` is the cheapest size — so a card price may fall outside the requested range. Compare against `sizePriceRange` on each result to see the actual span. | |
| query | No | Full-text query, e.g. "gucci сумка". Omit to browse the catalog without a text query. | |
| sizeIds | No | Size value ids (from oskelly_filter_values code='size'). | |
| sorting | No | NEW = newest first, PRICE_ASC / PRICE_DESC = by price, SCORE_DESC = by relevance (only meaningful with a query), PERSONALIZED = site's own ranking. | NEW |
| verbose | No | Return the raw upstream payload instead of the compact projection. Much larger. | |
| brandIds | No | Brand ids (from oskelly_list_brands or oskelly_filter_values code='brand'). | |
| modelIds | No | Model ids (from oskelly_filter_values code='model'). | |
| sellerIds | No | Restrict results to specific seller account ids. | |
| pageLength | No | Items per page (1-60). Keep small to limit response size. | |
| categoryIds | No | Leaf/branch category node ids (from oskelly_category_tree). | |
| baseCategory | No | Root segment node id from the category tree: 2 = Женское, 105 = Мужское, 188 = Детское, 366 = Лайфстайл. These are real tree node ids — read them from oskelly_category_tree rather than assuming. Omit to search all segments. | |
| conditionIds | No | Condition ids: 1 = Новое с биркой, 2 = Отличное, 3 = Хорошее. | |
| extraFilters | No | Escape hatch: raw filter entries merged into the request body verbatim, for facet codes discovered via oskelly_search_facets that this schema does not name yet. | |
| nameContains | No | Case-insensitive substring filter applied to returned value names. | |
| collectionIds | No | Collection ids: 5 = Новая коллекция, 6 = Sale, 7 = Аутлет. | |
| sellerTypeIds | No | Seller type ids (from oskelly_filter_values code='sellerType'). | |
| booleanFilters | No | Boolean facet toggles, e.g. {"sale": true, "vintage": true}. Available codes: sale, oskellyChoice, streetwear, newCollection, inStock, outlet, carry_over, celebrity_wardrobe, investment, vintage, brandNew, resale, exclusiveSelection, currentCollection | |
| boutiqueLocationTagIds | No | OSKELLY boutique location ids (from oskelly_filter_values code='boutiqueLocationTag'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds behavioral context beyond these: it mentions the response is scoped to the same search context and that returned values reflect the narrowed result set. It also notes that the output includes ids, which is helpful for chaining calls. No contradictions with annotations.
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 three sentences, front-loaded with the core purpose, followed by the key use case, and a closing note about search parameters. It wastes no words and every sentence earns its place. Length is appropriate for the tool's complexity.
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?
There is no output schema, so the description should convey return shape. It states 'List the selectable values (with their ids)' which implies a list of objects, but does not detail pagination or fields. However, for a facet listing tool with extensive parameter support, the description is sufficiently complete for an agent to invoke it 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 coverage is 100%, so baseline is 3. The description adds a concrete example of the 'code' parameter (brand vs size) and stresses that all search parameters are accepted, which helps understand filtering. However, it does not elaborate on syntax or behavior of individual params beyond what the schema already provides. This matches the baseline without exceeding it.
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 lists selectable values (with ids) for a single facet, scoped to search context. It gives a concrete use case (resolving human names to ids for oskelly_search_products) and differentiates from siblings by specifying it returns facet values. The verb 'List' plus resource 'values of one facet' is specific and 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 explains when to use it ('how you resolve a human name to the numeric id') and that it accepts all search parameters for narrowing. It does not explicitly exclude alternatives, but the purpose sentence makes clear it's for facet enumeration rather than search or tree browsing. Overall, the guidance is clear without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the full detail of a single oskelly.ru product by numeric id or product URL: description, condition, all attributes (material/colour/...), full size chart with per-size stock and pricing, breadcrumbs, every image, tags, and the seller's public profile. NOTE: oskelly.ru has no public JSON endpoint for a single product (/api/v2/products/{id} returns 404), so this reads the server-rendered Nuxt payload embedded in the product page and decodes it with the official devalue library.
| Name | Required | Description | Default |
|---|---|---|---|
| product | Yes | Numeric product id (e.g. "4703659") or a full product URL (e.g. "https://oskelly.ru/products/kurtka-christian-dior-pre-owned-4703659"). | |
| verbose | No | Return the raw upstream payload instead of the compact projection. Much larger. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly, openWorld, idempotent, not destructive), the description discloses a critical implementation behavior: there is no public JSON endpoint, so the tool parses the server-rendered Nuxt payload and decodes it with devalue. This is exactly the kind of non-obvious behavior an agent needs to know to trust and interpret results.
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: the first lists the product scope and included fields, the second explains the implementation workaround. Every sentence carries essential information, with no filler or repetition of annotations.
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?
For a tool that reads an embedded page payload instead of calling a normal API, the description gives the agent everything needed: what fields to expect, how the product identifier can be provided, what verbose does, and why the implementation is unconventional. No output schema exists, but the field list and verbose explanation compensate well.
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%, so the parameters are already fully described by the input schema. The description restates the product id/URL forms and the compact vs. verbose output concept, but does not add new parameter-level semantics beyond what the schema already documents.
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 opens with a specific verb-resource pairing ('Fetch the full detail of a single oskelly.ru product') and enumerates exactly what is included, making the tool's scope unmistakable. It clearly distinguishes from the sibling tools by focusing on a single product detail rather than search, facets, or seller lists.
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 makes the tool's use case evident: retrieving full single-product data by id or URL. It does not explicitly name alternatives like oskelly_search_products or oskelly_seller_products for comparison, but the context is clear enough that an agent would know when to choose this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the promotional banners / curated selections shown on the oskelly.ru homepage for a given audience segment: title, description, image, and the catalog link that opens the underlying selection. Feed a banner's catalogLink into oskelly_banner_catalog to see what products it actually resolves to.
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Audience segment: FEMALE | MALE | KIDS | LIFESTYLE. | FEMALE |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation as read-only, idempotent, and non-destructive. The description adds behavioral context by detailing the returned fields and the relationship with another tool (using catalogLink to resolve products). It does not contradict the annotations and provides useful information about the data structure and downstream usage.
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, composed of two sentences, with no redundant or extraneous content. It efficiently conveys the purpose, output fields, and a usage pointer. The structure is clear and appropriately sized for the tool's complexity.
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 that there is no output schema, the description adequately explains what the tool returns (title, description, image, catalog link). It also provides a suggestion for further action (feeding catalogLink to oskelly_banner_catalog). While it doesn't cover error handling or pagination, it is sufficiently complete for an agent to 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?
The input schema already provides a description for the 'category' parameter, including its enum values and default. The tool description reiterates 'for a given audience segment' but adds no new information beyond what the schema already specifies. Since the schema covers the parameter adequately, the description adds marginal value, aligning with the baseline score of 3.
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's function: returning homepage promotional banners for a given audience segment. It specifies the resource (homepage banners) and the action (return), and lists the output fields (title, description, image, catalog link). This distinguishes it from sibling tools that focus on search, filters, and product 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 when to use this tool: when you need banners for a specific audience segment. It also provides a follow-up usage hint by directing to oskelly_banner_catalog with the catalogLink. While it doesn't explicitly state when not to use this tool versus alternatives, the purpose is sufficiently distinct for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the product attribute dictionary (material, colour, style, ... ) with every possible value and its id. These are the attributes shown on a product card as 'Материал', 'Цвет' etc. Filter by name/code to keep the response small.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max attributes to return. | |
| nameContains | No | Case-insensitive substring on the attribute name or code, e.g. "цвет" or "COLOR". | |
| includeValues | No | Include each attribute's possible values (set false for just the attribute list). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which establishes the safety profile. The description adds value beyond this by clarifying the resource semantics — that it returns the full attribute dictionary with value ids and how it maps to the UI ('attributes shown on a product card'). It doesn't contradict the annotations and adds useful context about what the payload contains.
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?
Two concise sentences deliver everything efficiently: the core action with examples, contextual grounding, and a practical usage tip. No wasted words, front-loaded with the purpose, and every clause 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?
For a low-complexity listing tool with 3 optional parameters, full schema coverage, and a strong safety-annotation profile, the description is nearly complete. It could have mentioned pagination or the count of the full dictionary, but the combination of schema, annotations, and description leaves few meaningful gaps.
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 input schema already documents all 3 parameters at 100% coverage with clear descriptions including examples ('"цвет" or "COLOR"'), so the baseline is 3. The description's 'Filter by name/code' reinforces the nameContains parameter but adds minimal new meaning beyond what the schema already provides. The schema carries the semantic weight here.
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 a specific verb and resource ('List the product attribute dictionary... with every possible value and its id') and grounds it with real-world context ('attributes shown on a product card as 'Материал', 'Цвет''). It's clear about scope and differentiates itself through domain detail (catalog attribute dictionary vs. other tools), though it doesn't explicitly name or distinguish sibling tools like oskelly_filter_values.
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 performance tip 'Filter by name/code to keep the response small' implies usage context, and the description makes the purpose clear enough to infer when to call it. However, there's no explicit when-to-use vs. alternatives, and given siblings like oskelly_search_facets and oskelly_filter_values could overlap conceptually, some explicit exclusion or alternative mention would strengthen it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List brands available on oskelly.ru with their numeric ids (needed for the brandIds search filter), url slugs and transliterated Russian names. The full list is ~7000 brands, so filter with nameContains or page through with limit/offset.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max brands to return. | |
| offset | No | How many matches to skip. | |
| nameContains | No | Case-insensitive substring match on brand name or transliterated name, e.g. "guc". | |
| includeHidden | No | Include brands flagged isHidden (not surfaced in site navigation). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly, openWorld, idempotent, and non-destructive behavior, so the description adds extra value by disclosing the list size (~7000 brands) and recommending paging/filtering strategies. This goes beyond the baseline but doesn't describe all edge cases like default sorting or hidden brand behavior, which is acceptable given the annotations.
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, front-loaded with the primary purpose, and then adds behavioral context. Every word earns its place with no redundant phrases, making it highly efficient and easy to scan.
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?
For a list tool with 100% schema coverage, no required parameters, and no output schema, the description covers all necessary aspects: purpose, output fields, list size, and usage guidance. It is complete for an agent to decide when and how to invoke it without further clarification.
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%, so baseline is 3. The description adds meaningful context by connecting `nameContains` to filtering and limit/offset to paging, which clarifies their purpose beyond the schema descriptions. It also ties the output ids to search filter usage, enriching parameter comprehension.
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 lists brands from oskelly.ru with their numeric ids, URL slugs, and transliterated Russian names, and explicitly mentions the ids are needed for the `brandIds` filter. This differentiates it from sibling list tools (e.g., oskelly_list_conditions) by focusing on brands and their specific output fields.
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 clear context for when to use this tool: to obtain brand ids for the `brandIds` search filter. It also gives practical advice on handling the ~7000 brands by filtering with `nameContains` or using limit/offset for paging. However, it does not explicitly contrast with alternative tools, so it stops short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the product condition grades used on oskelly.ru (id, name and the full Russian explanation of what each grade guarantees). Condition ids feed the conditionIds filter.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds useful context beyond annotations by specifying the exact output content (id, name, full Russian explanation) and how the data is consumed by filters. No contradiction with annotations.
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, front-loaded with the core purpose, and every sentence adds value. It avoids redundancy and does not restate the tool name or title.
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?
For a zero-parameter, read-only list tool with rich annotations, the description is complete: it states what is returned, the language/scope of the explanations, and the practical purpose of the ids. No output schema exists, but the description sufficiently covers return value expectations.
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 the schema is fully covered by its empty properties definition. The description adds relevant context by explaining that condition ids feed the conditionIds filter, which is helpful even though no parameters need elaboration.
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 lists product condition grades on oskelly.ru, specifying the returned fields (id, name, full Russian explanation). It also distinguishes this from sibling tools like list_brands or list_attributes by tying the output to the conditionIds filter.
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 clear context for when to use the tool: to obtain condition ids that feed the conditionIds filter. It does not explicitly mention alternatives or when not to use it, but the filter-integration note provides enough practical guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the same search as oskelly_search_products but return the total result count plus the list of facets available for that result set (their codes, names, types, hot values and the price range present) instead of the products. Use this to discover which filters make sense before drilling down, or to count matches cheaply without fetching items.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number. | |
| price | No | Price range in RUB; at least one of lower/upper must be set. NOTE (verified live): the backend matches this per size/SKU, not against the card price. A product matches if ANY of its sizes is priced inside the range, and the returned card `price` is the cheapest size — so a card price may fall outside the requested range. Compare against `sizePriceRange` on each result to see the actual span. | |
| query | No | Full-text query, e.g. "gucci сумка". Omit to browse the catalog without a text query. | |
| sizeIds | No | Size value ids (from oskelly_filter_values code='size'). | |
| sorting | No | NEW = newest first, PRICE_ASC / PRICE_DESC = by price, SCORE_DESC = by relevance (only meaningful with a query), PERSONALIZED = site's own ranking. | NEW |
| verbose | No | Return the raw upstream payload instead of the compact projection. Much larger. | |
| brandIds | No | Brand ids (from oskelly_list_brands or oskelly_filter_values code='brand'). | |
| modelIds | No | Model ids (from oskelly_filter_values code='model'). | |
| sellerIds | No | Restrict results to specific seller account ids. | |
| pageLength | No | Items per page (1-60). Keep small to limit response size. | |
| categoryIds | No | Leaf/branch category node ids (from oskelly_category_tree). | |
| baseCategory | No | Root segment node id from the category tree: 2 = Женское, 105 = Мужское, 188 = Детское, 366 = Лайфстайл. These are real tree node ids — read them from oskelly_category_tree rather than assuming. Omit to search all segments. | |
| conditionIds | No | Condition ids: 1 = Новое с биркой, 2 = Отличное, 3 = Хорошее. | |
| extraFilters | No | Escape hatch: raw filter entries merged into the request body verbatim, for facet codes discovered via oskelly_search_facets that this schema does not name yet. | |
| collectionIds | No | Collection ids: 5 = Новая коллекция, 6 = Sale, 7 = Аутлет. | |
| sellerTypeIds | No | Seller type ids (from oskelly_filter_values code='sellerType'). | |
| booleanFilters | No | Boolean facet toggles, e.g. {"sale": true, "vintage": true}. Available codes: sale, oskellyChoice, streetwear, newCollection, inStock, outlet, carry_over, celebrity_wardrobe, investment, vintage, brandNew, resale, exclusiveSelection, currentCollection | |
| boutiqueLocationTagIds | No | OSKELLY boutique location ids (from oskelly_filter_values code='boutiqueLocationTag'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds behavioral context beyond annotations by specifying exactly what is returned (total count, facet codes/names/types/hot values/price range) and that it avoids fetching items, which is useful for cost expectations.
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?
Two front-loaded sentences: the first states exactly what the tool does, the second gives the primary use case. There is zero filler or redundancy.
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?
Despite having 18 parameters and no output schema, the description explains the returned facet fields and the use case, which is sufficient for a read-only facet-discovery tool. The schema covers parameters exhaustively, and the tool's purpose is simple enough that no further behavioral detail is needed.
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 input schema fully documents all 18 parameters. The description itself adds no parameter-level semantics, but it does not need to because the schema does the heavy lifting. Baseline 3 applies.
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 runs the same search as oskelly_search_products but returns the total result count and available facets instead of products. This distinguishes it from its sibling and specifies the exact resource and action.
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?
Explicitly tells the agent when to use it: to discover which filters make sense before drilling down or to count matches cheaply without fetching items. It also names the sibling alternative (oskelly_search_products), making the choice unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the oskelly.ru luxury marketplace catalog and return matching product cards (id, brand, category, price, discount, condition, in-stock sizes, seller, image, URL). Supports full-text query, faceted filtering (brand, category, size, condition, collection, model, seller type, boutique, price range, boolean tags such as sale/vintage/outlet), pagination and sorting. Use oskelly_search_facets first when you need to know which filter values are available, and oskelly_filter_values to resolve names to ids.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number. | |
| price | No | Price range in RUB; at least one of lower/upper must be set. NOTE (verified live): the backend matches this per size/SKU, not against the card price. A product matches if ANY of its sizes is priced inside the range, and the returned card `price` is the cheapest size — so a card price may fall outside the requested range. Compare against `sizePriceRange` on each result to see the actual span. | |
| query | No | Full-text query, e.g. "gucci сумка". Omit to browse the catalog without a text query. | |
| sizeIds | No | Size value ids (from oskelly_filter_values code='size'). | |
| sorting | No | NEW = newest first, PRICE_ASC / PRICE_DESC = by price, SCORE_DESC = by relevance (only meaningful with a query), PERSONALIZED = site's own ranking. | NEW |
| verbose | No | Return the raw upstream payload instead of the compact projection. Much larger. | |
| brandIds | No | Brand ids (from oskelly_list_brands or oskelly_filter_values code='brand'). | |
| modelIds | No | Model ids (from oskelly_filter_values code='model'). | |
| sellerIds | No | Restrict results to specific seller account ids. | |
| pageLength | No | Items per page (1-60). Keep small to limit response size. | |
| categoryIds | No | Leaf/branch category node ids (from oskelly_category_tree). | |
| baseCategory | No | Root segment node id from the category tree: 2 = Женское, 105 = Мужское, 188 = Детское, 366 = Лайфстайл. These are real tree node ids — read them from oskelly_category_tree rather than assuming. Omit to search all segments. | |
| conditionIds | No | Condition ids: 1 = Новое с биркой, 2 = Отличное, 3 = Хорошее. | |
| extraFilters | No | Escape hatch: raw filter entries merged into the request body verbatim, for facet codes discovered via oskelly_search_facets that this schema does not name yet. | |
| collectionIds | No | Collection ids: 5 = Новая коллекция, 6 = Sale, 7 = Аутлет. | |
| sellerTypeIds | No | Seller type ids (from oskelly_filter_values code='sellerType'). | |
| booleanFilters | No | Boolean facet toggles, e.g. {"sale": true, "vintage": true}. Available codes: sale, oskellyChoice, streetwear, newCollection, inStock, outlet, carry_over, celebrity_wardrobe, investment, vintage, brandNew, resale, exclusiveSelection, currentCollection | |
| boutiqueLocationTagIds | No | OSKELLY boutique location ids (from oskelly_filter_values code='boutiqueLocationTag'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds the return-card field list and enumerates filtering, pagination, and sorting capabilities, giving a clear behavioral model. No contradiction with annotations.
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 three sentences, front-loaded with the action and resource, followed by capabilities and sibling guidance. Every sentence earns its place with no redundant filler.
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?
For an 18-parameter search tool with no output schema, the description gives a compact but sufficient overview: output fields, supported filter types, pagination/sorting, and helper-tool pointers. The rich schema carries per-parameter details, so the description does not need to enumerate them.
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%, with detailed per-parameter descriptions such as the price-range per-size matching behavior and id source endpoints. The description adds only a high-level summary of filter dimensions, which is useful but not necessary given the schema. Baseline 3 applies.
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 opens with 'Search the oskelly.ru luxury marketplace catalog and return matching product cards', naming a specific verb, resource, and output fields. It also distinguishes itself from siblings by directing use of oskelly_search_facets and oskelly_filter_values for filter discovery.
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?
It explicitly says 'Use oskelly_search_facets first when you need to know which filter values are available, and oskelly_filter_values to resolve names to ids', giving concrete when-to-use guidance for related tools. It does not cover every alternative such as oskelly_get_product for single-item lookups, but the main discovery workflow is clearly addressed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get search-query autocomplete suggestions from oskelly.ru for a partial user query. Useful for discovering how the marketplace phrases things (brand + item combinations) before running a full search.
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | Number of suggestions. | |
| userQuery | Yes | Partial query, e.g. "guc" or "сумка". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds that it returns suggestions for a partial query, which is already implied by schema. It doesn't disclose behavior like result format or any rate limits, but no contradictions and a neutral score is appropriate.
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, front-loaded with the core purpose, and provides a usage tip. Zero waste, efficient.
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?
The tool is simple with only 2 parameters and no output schema. The description explains its purpose and typical usage. It doesn't detail return structure, but given the output schema absence and low complexity, it's adequate. Could mention what format results come in, but not critical.
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%, so both parameters are documented with descriptions. The description adds minimal extra meaning—it mentions 'partial user query' which aligns with userQuery schema. With full schema coverage, baseline 3 is correct; the description doesn't add significant value beyond 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 clearly states the tool's purpose: getting search-query autocomplete suggestions from oskelly.ru for a partial query. It distinguishes itself from other search-related siblings by focusing on autocomplete suggestions for partial input, though it doesn't explicitly compare to 'oskelly_search_products' or 'oskelly_search_facets'.
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?
It states a clear use case: discovering how the marketplace phrases things before running a full search. This implies it's a preliminary step and guides the agent to use it before a full search, but it doesn't explicitly mention when not to use it or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the sets of ids that actually occur in one seller's inventory — which attribute values, categories, brands, sizes and conditions they carry. Use it to understand a seller's assortment before filtering their catalog.
| Name | Required | Description | Default |
|---|---|---|---|
| verbose | No | Return the raw upstream payload instead of the compact projection. Much larger. | |
| sellerId | Yes | Numeric seller account id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe-read profile is fully captured. The description adds the scoping detail that results reflect only IDs 'that actually occur in one seller's inventory,' which helps set expectations, but it doesn't disclose response internals or upstream behavior. With the annotations covering the safety profile, the description provides modest added context beyond the structured data.
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?
Two compact sentences do all the work: the first states the exact output, the second explains when to use it. No wasted words.
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?
For a simple, two-parameter, read-only operation with comprehensive annotations, the description is complete: it states what it returns, why you'd use it, and its scope. Absence of an output schema means the description doesn't need to explain return values.
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 both sellerId and verbose are documented in the schema. The description adds no param-specific detail beyond what the schema already provides, so the baseline of 3 applies.
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 a specific verb+resource construction: 'Return the sets of ids that actually occur in one seller's inventory' and enumerates the filter types (attribute values, categories, brands, sizes, conditions). This clearly differentiates it from sibling tools by emphasizing seller-specific, actually-occurring values rather than global facets or suggestions.
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 second sentence provides direct guidance: 'Use it to understand a seller's assortment before filtering their catalog.' This gives clear context for when to invoke it, though it stops short of naming alternatives or explicitly contrasting with siblings like oskelly_describe_filters or oskelly_search_facets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the products currently offered by a specific oskelly.ru seller (boutique, brand or private seller), with pagination and sorting. Seller ids come from the seller block of any product card or from oskelly_get_product.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number. | |
| sorting | No | Optional sort order, same codes as product search. | |
| verbose | No | Return the raw upstream payload instead of the compact projection. Much larger. | |
| sellerId | Yes | Numeric seller account id. | |
| pageLength | No | Items per page (1-60). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds context about pagination and sorting, and mentions the source of seller IDs. It does not contradict annotations.
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, efficient and clear. It covers purpose and how to find seller ID without unnecessary detail.
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 simple nature of listing with pagination/sorting, and schema covering all params, the description is sufficient. It does not detail return format, but likely not needed as it's a list with compact projection option via 'verbose'.
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 schema has 100% coverage with descriptions for each parameter. The tool description adds context about seller IDs sourcing, but parameters like sorting and verbose are already well described. No additional parameter semantics needed beyond 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 clearly states the tool lists products for a specific seller with pagination and sorting. It distinguishes from siblings by mentioning seller context and references getting seller IDs from the 'seller' block or oskelly_get_product.
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?
It explains when to use (for a specific seller's products) and how to find seller IDs. It doesn't explicitly mention alternatives, but the sibling tools are clear enough (search_products vs seller_products).
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.
v1.0.0oskelly_banner_catalogoskelly_category_treeoskelly_describe_filtersoskelly_filter_valuesoskelly_get_productoskelly_home_bannersoskelly_list_attributesoskelly_list_brandsoskelly_list_conditionsoskelly_search_facetsoskelly_search_productsoskelly_search_suggestionsoskelly_seller_filtersoskelly_seller_productsScored across 14 tools
Each tool targets a distinct resource or action: search, facet discovery, filter value resolution, autocomplete, category tree, dictionary lookups, product detail, seller queries, and banner catalogs. Even the two facet-related tools are explicitly differentiated by what they return.
The dominant pattern is oskelly_<verb>_<object> (search_products, list_brands, get_product, describe_filters). A few names omit the verb (seller_products, home_banners, banner_catalog), but they are still predictable and readable.
14 tools is within the well-scoped range and each one covers a meaningful browsing need, from category and dictionary lookups to search, product detail, seller inventory, and curated banners. No tool feels redundant.
The read-only marketplace browsing surface is well covered: discovery via suggestions/categories/brands/conditions/attributes, faceted search, product detail, seller-focused queries, and banner-driven curated catalogs. The filter cheat-sheet and facet/filter value tools close the gap between filter names and the ids that search_products expects.
MCP server for Russian books search, details, and recommendation candidates.
Unified MCP server for 70+ eCommerce platforms: products, orders, customers, and more.
MCP server for Product Management
MCP server for ua_e_commerce_price_tracker_mcp