让你的 AI 助手能够访问 Vinted — 在 19 个国家/地区进行搜索、比价和追踪卖家。
Vinted 没有公开的 API。此包填补了这一空白 — 它允许 AI 助手通过 Model Context Protocol 直接与 Vinted 对话。
将其连接到 Claude、Cursor 或任何支持 MCP 的助手，只需询问：
“帮我在德国找一件 60 欧元以下的 North Face 夹克，成色要在良好及以上”
“比较一下法国、意大利和英国的 Air Jordan 1 价格”
“卖家 #123456 目前在卖什么？有 20 欧元以下的吗？”
AI 会自动判断使用哪些过滤器，调用 Vinted，并给你一个直接的答案 — 无需手动搜索、筛选或切换标签页。
同时提供 CLI 工具 和 TypeScript 库 以供直接使用。
Related MCP server: qontoctl
这是一个用于 Vinted 二手交易平台的 MCP 服务器、CLI 工具 和 TypeScript 库。它没有官方 API — 它通过公共目录页面引导会话 cookie，并调用 Vinted Web 应用内部使用的私有 JSON API。
🤖 MCP 服务器 — 插入 Claude、Cursor 或任何支持 MCP 的 AI 助手
🖥️ CLI 工具 — 在终端中管道输出结果、监控新商品、比较价格
📦 TypeScript 库 — 在你的代码中直接导入 opSearch、opCompare 等
npm install -g @googlarz/vinted-client或者直接运行而不安装：
npx @googlarz/vinted-client search "levis 501"# Search (JSON by default)
vinted search "levi's 501" --country fr
# Pretty table
vinted search "levi's 501" --country de --output table
# Filter by price, brand, condition
vinted search "adidas samba" \
--price-min 20 --price-max 80 \
--brand adidas \
--condition new_with_tags,very_good \
--output table
# Watch for new listings every 30s
vinted search "air jordan 1" --watch 30
# Walk all pages and collect up to 500 results
vinted search "vintage denim" --all --max-items 500
# Get a specific item (ID or URL)
vinted item 1234567
vinted item https://www.vinted.fr/items/1234567
# Seller profile + active listings
vinted seller 987654
vinted seller-items 987654 --output table
# Cross-country price comparison (6 countries by default)
vinted compare "north face jacket" --output table
# Browse category tree
vinted categories --query shoes --output table
# Look up brand IDs
vinted brands "stone island"
# What's trending right now
vinted trending --country fr --output table命令 | 描述 | |
| 使用完整的过滤器支持搜索商品 | |
`item <id | url>` | 获取完整的商品详情 |
| 卖家资料 | |
| 卖家在售商品 | |
| 跨国家价格比较 | |
| 按名称查找品牌 ID | |
| 浏览分类树 | |
| 最新/热门商品 | |
| 检查会话 cookie（用于故障排除） |
标志 | 描述 | |
`--output json | table` | 输出格式（默认： |
| 国家代码（见下文） | |
| HTTP/HTTPS 代理（也可使用： | |
| 禁用响应缓存 |
标志 | 描述 |
| 价格范围 |
| 品牌名称（自动解析为 ID） |
| 逗号分隔的品牌 ID |
| 分类 ID（使用 |
| 逗号分隔的尺寸 ID |
|
|
|
|
| 日期范围过滤器 (YYYY-MM-DD) |
| 遍历页面并收集所有结果 |
|
|
| 每 N 秒轮询一次新商品（默认 60 秒） |
fr de uk it es nl pl pt be at lt cz sk hu ro hr fi dk se
将 Vinted 放入任何支持 MCP 的 AI 助手（Claude、Cursor 等）中。
添加到 claude_desktop_config.json：
{
"mcpServers": {
"vinted": {
"command": "npx",
"args": ["-y", "@googlarz/vinted-client/mcp"]
}
}
}claude mcp add vinted -- npx -y @googlarz/vinted-client/mcp工具 | 描述 |
| 使用完整的过滤器支持进行搜索 |
| 按 ID 或 URL 获取商品详情 |
| 卖家资料 |
| 卖家的在售商品 |
| 跨国家价格比较 |
| 热门商品 |
| 品牌查找 |
| 分类树 |
连接后的示例提示词：
“帮我在德国找 70 欧元以下的 Nike Air Max 95，43 码，成色非常好”
“比较一下法国、德国和意大利的 North Face 羽绒服价格”
“监控卖家 #987654，当他们上架 30 欧元以下的商品时通知我”
import { VintedClient, opSearch, opCompare, opSearchAll } from '@googlarz/vinted-client';
const client = new VintedClient();
// Basic search
const results = await opSearch(client, {
query: 'levi\'s 501',
country: 'de',
priceMax: 50,
condition: ['very_good', 'good'],
sortBy: 'price_low_to_high',
});
console.log(results.items);
// Collect all pages concurrently (3-page prefetch window)
const all = await opSearchAll(client, {
query: 'vintage band tee',
country: 'uk',
maxItems: 300,
});
// Multi-country price comparison
const report = await opCompare(client, {
query: 'air jordan 1 retro',
countries: ['fr', 'de', 'uk', 'it'],
});const client = new VintedClient({
proxyUrl: 'http://proxy:8080', // or VINTED_PROXY_URL env var
cacheTtlMs: 60_000, // response cache TTL (0 = disable)
rateLimitPerSec: 3, // requests/sec per country
rateLimitBurst: 6, // burst capacity
timeoutMs: 20_000, // per-request timeout
});Vinted 没有公开的 API。此库：
引导会话：通过访问 vinted.{cc}/catalog 并捕获 Vinted 前端设置的身份验证 cookie。
调用私有 JSON API (/api/v2/...)：使用这些 cookie，模拟浏览器请求头。
自动重新引导：在遇到 401 错误时 — 令牌过期后，库会自动静默恢复。
按国家/地区限流：使用令牌桶算法（可配置突发和填充速率）以避免 429 错误。
缓存响应：使用 LRU+TTL — 搜索结果缓存 60 秒，分类等静态数据缓存 1 小时。
回退到 HTML 抓取：对于被 DataDome 拦截的商品页面，使用 HTML 抓取（JSON-LD + 正则表达式提取）。
并发预取 3 页：在 opSearchAll 中并发预取，以在限流预算内最大化吞吐量。
如果 Vinted 封锁了你的 IP（在云虚拟机和 CI 上很常见），请设置代理：
VINTED_PROXY_URL=http://user:pass@proxy:8080 vinted search "nike"
# or
vinted search "nike" --proxy http://user:pass@proxy:8080同时也支持标准的 HTTPS_PROXY / HTTP_PROXY 环境变量。
变量 | 描述 |
| HTTP/HTTPS 代理 URL |
| 缓存 TTL（毫秒，默认 |
| 每个国家每秒请求数（默认 |
| 令牌桶突发大小（默认 |
| 设置为 |
Node.js ≥ 18
可选：playwright + puppeteer-extra-plugin-stealth 用于 --browser / VINTED_BROWSER=1 模式
MIT © googlarz
Compare prices for a search query across multiple Vinted country sites simultaneously. Returns median, mean, min, max, standard deviation, and sample count per country along with the local currency. Useful for finding the cheapest market to buy a specific item or understanding cross-border price gaps.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of listings to sample per country. Higher values give more accurate statistics (max 96). | |
| query | Yes | Item to compare prices for, e.g. "Levi 501 jeans" or "iPhone 14 case" | |
| countries | No | List of country codes to compare. Defaults to all 19 Vinted countries if omitted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description reveals key behaviors: it returns statistical aggregations per country, samples listings (via limit parameter), and defaults to all countries. It does not mention real-time vs. cached data, but read operations can have such ambiguity.
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 sentences, no waste. First sentence explains core function, second adds output details and use cases. Efficient and front-loaded.
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 covers return values sufficiently. It explains the sampling behavior and default countries. Lacks details on error handling or rate limits, but for a simple comparison tool, it is complete enough.
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 all parameters are described in the schema. The description reinforces the limit and countries default but adds little new meaning beyond the schema. Baseline score of 3 is appropriate.
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 compares prices across multiple Vinted countries simultaneously. It specifies the verb (compare), resource (prices), and output statistics (median, mean, etc.), distinguishing it from siblings like search_items or get_trending.
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 a clear use case: finding the cheapest market or understanding cross-border price gaps. It does not explicitly state when not to use or mention alternative tools, but the context is sufficient for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the full Vinted category tree for a country. Returns a flat list of all categories and subcategories with their numeric IDs, names, parent IDs, and item counts. Pass a categoryId to search_items or search_all_items to restrict results to a department (e.g. women's clothing, men's shoes, electronics). Results are cached for 1 hour.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Optional keyword filter on category name, e.g. "shoes" or "dress" | |
| country | No | Country site to fetch categories for (category IDs are consistent across countries) | fr |
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 discloses caching behavior (1 hour) and the return structure. However, it does not mention idempotency, rate limits, or authentication requirements. The description adds value beyond the schema but lacks some behavioral depth.
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 main action, and every sentence adds value. It efficiently explains purpose, usage, and caching 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?
The description covers the tool's purpose, return fields, caching, and integration with sibling tools. Given the simple input schema and no output schema, it provides sufficient context for an agent to use the tool correctly. Minor gaps like error handling are 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?
Input schema has 100% coverage with clear descriptions for country and query. The description does not add new semantic information about the parameters beyond what is in the schema. According to the guidelines, baseline is 3 when coverage is high, and the description does not enhance it further.
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 fetches the full Vinted category tree for a country, listing the return fields (IDs, names, parent IDs, item counts). It is specific and distinguishes from sibling tools like search_brands or get_size_groups.
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 the tool (to get categories for a country) and how to use the output (pass categoryId to search_items/search_all_items). It does not explicitly state when not to use it or list alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the complete list of Vinted color options available as search filters. Returns every color with its numeric ID, display name, hex color code, short code (e.g. "BLACK"), and sort order. Pass the returned IDs to search_items.colorIds or search_all_items.colorIds to restrict results to specific colors. Results are cached for 1 hour — color catalogues change rarely.
| Name | Required | Description | Default |
|---|---|---|---|
| country | No | Vinted country site to query (color catalogues are shared across countries) | fr |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden. It discloses that results are cached for 1 hour and color catalogues change rarely, and describes the exact return fields (numeric ID, display name, hex code, short code, sort order).
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 four sentences, each earning its place: purpose, output details, usage, caching policy. No filler, well front-loaded.
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 fetch tool with one parameter and no output schema, the description fully covers purpose, output structure, usage guidance, and caching behavior. It leaves no 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?
Schema coverage is 100% for the only parameter (country), so baseline is 3. The description does not add new detail beyond what the schema already provides about the country parameter; it only restates shared-country info from 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 clearly states 'Fetch the complete list of Vinted color options' with a specific verb and resource, and it distinguishes itself from sibling tools like get_categories or get_size_groups by focusing exclusively on color data.
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 explicitly tells users to pass the returned IDs to search_items.colorIds or search_all_items.colorIds, showing when to use this tool vs others. It also mentions caching behavior but does not include explicit when-not-to-use statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch complete item details by Vinted item ID (with country) or by a direct Vinted item URL. Returns title, price, currency, brand, size, condition, full description, all photo URLs, creation date, item URL, favourite count, and seller username/ID. Automatically falls back to HTML scraping when the JSON API is unavailable.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Full Vinted item URL, e.g. "https://www.vinted.fr/items/5678901234-nike-air-max". Country is inferred from the URL automatically. | |
| itemId | No | Numeric Vinted item ID, e.g. 5678901234 | |
| browser | No | Use headless browser for retrieval. Requires optional Playwright deps; only needed for items blocked by bot detection. | |
| country | No | Country site (required when using itemId; inferred automatically when url is provided) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool falls back to HTML scraping when the JSON API is unavailable, which is important behavioral context. It also mentions the optional browser parameter for bot detection. No annotations are present, so the description carries the full burden.
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 with no redundancy. It front-loads the core purpose, lists return fields, and appends the fallback behavior. Every sentence contributes meaningful 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 moderate complexity (4 parameters, no output schema), the description covers all key aspects: input modes, return fields, and fallback behavior. It does not explain error cases or rate limits, but that is acceptable for a read-only tool with good schema coverage.
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 provides full descriptions, but the tool description adds valuable context: clarifies that country is required with itemId (when omitted from schema), that url automatically infers country, and that browser is for bot detection requiring Playwright. This enhances understanding 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 clearly states that the tool fetches complete item details by Vinted item ID (with country) or by a direct URL. It distinguishes from siblings like search_items or get_seller by focusing on a single item's full 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 specifies when to use the tool (to get detailed info for a specific item) and how (via ID+country or URL). It doesn't explicitly state when not to use it or mention alternatives, but the context makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a seller's public profile by their numeric user ID. Returns username, active listing count, feedback reputation score (0–1 float), total feedback count, country code, and profile URL. Use get_seller_feedback to read review texts and star ratings, and get_seller_items to browse their listings.
| Name | Required | Description | Default |
|---|---|---|---|
| country | No | Country site where the seller is registered | fr |
| sellerId | Yes | Numeric Vinted user ID, visible in profile URLs: vinted.fr/member/12345-username |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses returned fields but does not mention read-only nature, authorization requirements, or rate limits. Adequate but lacks behavioral context beyond output.
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. Purpose and alternatives are front-loaded. No 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?
No output schema, so description lists all return fields: username, active listing count, feedback score (0–1 float), total feedback count, country code, profile URL. Complete for a profile fetch tool.
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%. Description adds value by explaining that sellerId is 'Numeric Vinted user ID, visible in profile URLs' and that country has a default of 'fr'. Provides useful context 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 starts with a clear verb+resource: 'Fetch a seller's public profile by their numeric user ID.' It also lists the specific fields returned, and distinguishes from siblings by naming get_seller_feedback and get_seller_items.
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 states when to use this tool (fetch profile) and directs to alternatives for reviews and listings: 'Use get_seller_feedback to read review texts and star ratings, and get_seller_items to browse their listings.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch paginated buyer and seller feedback reviews for a Vinted user. Each entry includes the review text, star rating (1–5), feedback type (1=negative, 2=neutral, 3=positive), reviewer username, timestamp, and the associated item ID. Use this to assess seller trustworthiness and reliability before making a purchase.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number starting at 1 | |
| limit | No | Reviews per page, 1–100 | |
| country | No | Country site where the seller is registered | fr |
| sellerId | Yes | Numeric Vinted user ID (visible in profile URLs: vinted.fr/member/12345-username) |
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 'paginated' and describes the output fields, but it does not disclose error handling, rate limits, or authentication requirements. This is adequate but not thorough.
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 sentences: first defines the tool's action and output, second provides the use case. It is front-loaded and every sentence is informative with no fluff.
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 there is no output schema, the description adequately lists the return fields. It is fairly complete for a list tool, though it could mention pagination limits or ordering. Sibling tools are distinct enough.
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. The description does not add additional parameter meaning beyond what the schema already provides; it focuses on output fields. No extra value for 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?
The description clearly states 'Fetch paginated buyer and seller feedback reviews for a Vinted user' with a specific verb and resource. It lists the fields included, making the output clear. It distinguishes itself from siblings like get_seller and get_seller_items by focusing on feedback.
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 a concrete use case: 'Use this to assess seller trustworthiness and reliability before making a purchase.' It does not explicitly mention when to avoid using it or alternative tools, but the context is clear enough for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all items currently for sale by a specific seller, paginated. Returns the same fields as search_items (title, price, brand, size, condition, photo URL, item URL). Useful for browsing a seller's full catalogue after finding them via search_items or get_seller.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number starting at 1 | |
| limit | No | Items per page, 1–100 | |
| country | No | Country site where the seller is registered | fr |
| sellerId | Yes | Numeric Vinted user ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must cover behavioral traits. It mentions pagination and dynamic data ('currently for sale'), but lacks details on auth needs, rate limits, or nondestructive nature.
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 with no wasted words, front-loaded with the primary 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?
With complete schema coverage and no output schema, the description sufficiently explains the tool's return structure (same as search_items) and pagination. Additional details about pagination behavior are not necessary given the 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?
Schema coverage is 100%, and the description adds marginal value by noting the return fields match search_items. Parameters are adequately explained in 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 clearly states the verb 'list' and resource 'items for sale by a specific seller', includes pagination, and distinguishes from siblings by specifying it returns the same fields as search_items.
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?
Description explicitly mentions it is useful after finding a seller via search_items or get_seller, but does not provide explicit when-not-to-use or alternative scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch all Vinted size groups with their constituent size IDs and labels. Returns a list of size groups (e.g. "Women's clothing", "Men's shoes", "Kids 2–8 yrs") — each containing the group ID, caption, description, and an array of sizes with numeric IDs and display titles (e.g. "XS", "42", "12 UK"). Pass individual size IDs from the sizes array to search_items.sizeIds or search_all_items.sizeIds to filter listings to an exact size. Results are cached for 1 hour.
| Name | Required | Description | Default |
|---|---|---|---|
| country | No | Vinted country site to query (size catalogues are shared across countries) | fr |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It states that results are cached for 1 hour, which is a key behavioral trait. No contradictions are present. The score reflects good transparency but a slight gap (e.g., no mention of rate limits or potential errors).
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 tightly written with no wasted words. It front-loads the purpose, explains the output structure, provides usage guidance, and mentions caching—all in a compact paragraph.
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 thoroughly explains the return structure (list of groups with IDs, captions, descriptions, and array of sizes with numeric IDs and display titles). It also explains how to use the output, making it fully complete for an agent.
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 coverage is 100%, so the parameter descriptions are already present. The description adds useful context: 'size catalogues are shared across countries', which goes beyond the schema. This extra insight warrants 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 starts with 'Fetch all Vinted size groups with their constituent size IDs and labels', which is a specific verb+resource combination. It clearly identifies the tool's purpose and distinguishes it from sibling tools like get_categories or get_colors.
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 how to use the output by passing size IDs to search_items.sizeIds or search_all_items.sizeIds. It provides clear context but does not explicitly state when not to use this tool or mention alternatives, which keeps it from a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the newest and trending items on Vinted for a given country, ordered by recency. Optionally scoped to a specific category. Useful for discovering what's currently popular, monitoring new arrivals, or finding deals as they are listed.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of trending items to return, 1–96 | |
| country | No | Vinted country site to fetch trending items from | fr |
| categoryId | No | Optional category ID from get_categories to restrict results to a specific department |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose behavior. It correctly describes the fetch as read-only and ordered by recency, but lacks details on authentication, rate limits, or pagination. This is adequate but minimal.
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 sentences with no wasted words. The first sentence states the core action and constraints; the second provides usage guidance. Efficient and well-structured.
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 description covers the main purpose and usage scenarios. Missing details about pagination behavior or result format are minor; the limit parameter and ordering are mentioned. With no output schema, the description is reasonably complete for a simple list tool.
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. The description adds that scope is optional and items are ordered by recency, but these are already implied by schema descriptions. No additional 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 it fetches the newest and trending items on Vinted for a given country, ordered by recency, with optional category scoping. This distinguishes it from sibling tools like search_items (general search) and get_seller_items (specific seller's items).
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 usage context: useful for discovering popular items, monitoring new arrivals, or finding deals. While it doesn't explicitly state when not to use or name alternatives, the context is sufficient given sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Vinted listings and automatically paginate through all results, returning up to maxItems items in a single call. Use this instead of search_items when you need comprehensive results — e.g. "find all Nike shoes under €30" or "list every item in size M from this brand". Pages are fetched concurrently for speed. Returns the same item fields as search_items.
| Name | Required | Description | Default |
|---|---|---|---|
| brand | No | Brand names; automatically resolved to IDs | |
| query | Yes | Search keywords | |
| sortBy | No | Sort order | |
| country | No | Vinted country site to search | fr |
| sizeIds | No | Size IDs to filter by | |
| brandIds | No | Numeric brand IDs from search_brands | |
| colorIds | No | Color IDs to filter by. Use get_colors to discover all available color IDs. | |
| maxItems | No | Maximum total items to collect across all pages (default 200, max 1000) | |
| maxPages | No | Maximum number of pages to fetch regardless of maxItems | |
| priceMax | No | Maximum price in local currency | |
| priceMin | No | Minimum price in local currency | |
| condition | No | Item condition filter | |
| categoryId | No | Category ID from get_categories |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description discloses concurrency ('Pages are fetched concurrently for speed'), pagination behavior, and return field compatibility. Does not mention rate limits or error handling, but key behaviors are covered.
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?
Highly concise: two sentences cover purpose, usage, behavior, and output. Every sentence adds value with 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?
13 parameters all documented in schema; description adds pagination, concurrency, and output reference. Could mention limit behavior but overall sufficient for agent to use effectively.
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 each parameter has its own description. The tool description does not add significant new meaning beyond the schema; baseline 3 is appropriate.
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?
Clear verb and resource: 'Search Vinted listings' with automatic pagination. Explicitly distinguishes from sibling 'search_items' by stating use case for comprehensive results.
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 states when to use ('instead of search_items when you need comprehensive results') with concrete examples. Lacks explicit 'when not to use' but the guidance is clear for the intended scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Vinted's brand catalogue by keyword. Returns matching brands with their numeric IDs, slugs, total item counts, and favourite counts. Pass the returned IDs to search_items.brandIds, or use search_items.brand[] to pass names and have them resolved automatically.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of brand results to return | |
| query | Yes | Brand name keyword to search for, e.g. "Nike" or "Levi" | |
| country | No | Country site to query (brand catalogues are shared across countries) | fr |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description bears full burden. It explains the output structure but does not disclose read-only nature, rate limits, or authentication requirements. As a search tool, it is likely safe, but the description could be more explicit about behavioral traits.
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 with front-loaded purpose. No wasted words. Effectively communicates the tool's action and additional integration guidance.
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 covers return fields adequately. Parameters are fully documented. Lacks behavioral disclosures (read-only, errors) but for a simple search tool, the completeness is 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?
Schema description coverage is 100%, providing full parameter definitions. The description adds usage context (output integration) but does not enhance parameter semantics beyond the schema. Baseline score of 3 is appropriate.
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 searches Vinted's brand catalogue by keyword and lists the specific return fields (IDs, slugs, counts). It also differentiates by showing how to use the output with search_items, making it distinct from sibling tools.
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?
Provides explicit guidance on using the returned IDs with search_items.brandIds or brand[] for automatic resolution. This implies when to use the tool, but lacks explicit exclusion or comparison to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Vinted second-hand listings with rich filters across 19 country sites. Returns a paginated list of items — each with title, price, currency, brand, size, condition, photo URL, item URL, favourite count, and seller info. Use get_categories to discover valid categoryId values and search_brands to resolve brand names to IDs. For comprehensive multi-page results use search_all_items instead.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number starting at 1 | |
| brand | No | Brand names to filter by, e.g. ["Nike", "Adidas"]. Automatically resolved to IDs via search_brands. | |
| query | Yes | Search keywords, e.g. "Nike Air Max 90" or "levi 501 jeans" | |
| dateTo | No | Return items listed on or before this date. ISO-8601 format, e.g. "2024-12-31" | |
| sortBy | No | Sort order for results. Defaults to relevance. | |
| country | No | Vinted country site to search (fr, de, uk, pl, es, nl, be, it, pt, cz, sk, hu, ro, lt, lv, ee, fi, at, se) | fr |
| perPage | No | Results per page, 1–96. Defaults to 20. | |
| sizeIds | No | Size IDs to filter by. Discover valid IDs by inspecting results from a previous search in the same category, or use get_size_groups to browse all size groups. | |
| brandIds | No | Numeric Vinted brand IDs from search_brands. Prefer the brand[] parameter for name-based lookup. | |
| colorIds | No | Color IDs to filter by (e.g. [1] for black, [3] for white). Use get_colors to discover all available color IDs and their names. | |
| dateFrom | No | Return items listed on or after this date. ISO-8601 format, e.g. "2024-01-01" | |
| priceMax | No | Maximum price in the local currency of the selected country | |
| priceMin | No | Minimum price in the local currency of the selected country | |
| condition | No | Item condition filter; multiple values are OR-ed together | |
| categoryId | No | Category ID from get_categories (e.g. 4 = women's clothing, 5 = men's clothing, 1231 = women's shoes) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It details the return fields (title, price, etc.) and mentions pagination and 19 country sites. Could improve by noting authentication or rate limits, but overall sufficiently transparent.
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: first states purpose, second details return fields, third provides usage guidance. Front-loaded and no unnecessary 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?
With 15 params and no output schema or annotations, description covers core behavior, return structure, and related tools. Missing mention of authentication, but sufficient for agent decision-making.
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% (baseline 3). Description adds value by explaining how to get category IDs (get_categories), brand resolution (search_brands), and size IDs (get_size_groups), going beyond schema 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 'Search Vinted second-hand listings with rich filters across 19 country sites', specifying the verb 'search' and resource 'listings'. It distinguishes itself from sibling tools like search_all_items and get_item.
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 advises using get_categories for category IDs and search_brands for brand IDs, and directly says to use search_all_items for comprehensive multi-page results, providing clear when-to-use and alternatives.
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.2get_colorsget_size_groupssearch_all_items1 field changedInput schema / properties / colorIdsAdded value: +{
+ "description": "Color IDs to filter by. Use get_colors to discover all available color IDs.",
+ "items": {
+ "type": "integer"
+ },
+ "type": "array"
+}search_items2 fields changedInput schema / properties / colorIdsAdded value: +{
+ "description": "Color IDs to filter by (e.g. [1] for black, [3] for white). Use get_colors to discover all available color IDs and their names.",
+ "items": {
+ "type": "integer"
+ },
+ "type": "array"
+}Input schema / properties / sizeIds / descriptionPrevious value: -"Size IDs to filter by. Discover valid IDs by inspecting results from a previous search in the same category."New value: +"Size IDs to filter by. Discover valid IDs by inspecting results from a previous search in the same category, or use get_size_groups to browse all size groups."v1.0.1compare_prices3 fields changedInput schema / properties / countries / descriptionAdded value: +"List of country codes to compare. Defaults to all 19 Vinted countries if omitted."Input schema / properties / limit / descriptionAdded value: +"Number of listings to sample per country. Higher values give more accurate statistics (max 96)."Input schema / properties / query / descriptionAdded value: +"Item to compare prices for, e.g. \"Levi 501 jeans\" or \"iPhone 14 case\""get_categories2 fields changedInput schema / properties / country / descriptionAdded value: +"Country site to fetch categories for (category IDs are consistent across countries)"Input schema / properties / query / descriptionPrevious value: -"Optional keyword filter on category name"New value: +"Optional keyword filter on category name, e.g. \"shoes\" or \"dress\""get_item4 fields changedInput schema / properties / browser / descriptionAdded value: +"Use headless browser for retrieval. Requires optional Playwright deps; only needed for items blocked by bot detection."Input schema / properties / country / descriptionAdded value: +"Country site (required when using itemId; inferred automatically when url is provided)"Input schema / properties / itemId / descriptionAdded value: +"Numeric Vinted item ID, e.g. 5678901234"Input schema / properties / url / descriptionAdded value: +"Full Vinted item URL, e.g. \"https://www.vinted.fr/items/5678901234-nike-air-max\". Country is inferred from the URL automatically."get_seller2 fields changedInput schema / properties / country / descriptionAdded value: +"Country site where the seller is registered"Input schema / properties / sellerId / descriptionAdded value: +"Numeric Vinted user ID, visible in profile URLs: vinted.fr/member/12345-username"get_seller_feedbackget_seller_items4 fields changedInput schema / properties / country / descriptionAdded value: +"Country site where the seller is registered"Input schema / properties / limit / descriptionAdded value: +"Items per page, 1–100"Input schema / properties / page / descriptionAdded value: +"Page number starting at 1"Input schema / properties / sellerId / descriptionAdded value: +"Numeric Vinted user ID"get_trending3 fields changedInput schema / properties / categoryId / descriptionAdded value: +"Optional category ID from get_categories to restrict results to a specific department"Input schema / properties / country / descriptionAdded value: +"Vinted country site to fetch trending items from"Input schema / properties / limit / descriptionAdded value: +"Number of trending items to return, 1–96"search_all_itemssearch_brands3 fields changedInput schema / properties / country / descriptionAdded value: +"Country site to query (brand catalogues are shared across countries)"Input schema / properties / limit / descriptionAdded value: +"Maximum number of brand results to return"Input schema / properties / query / descriptionAdded value: +"Brand name keyword to search for, e.g. \"Nike\" or \"Levi\""search_items14 fields changedInput schema / properties / brand / descriptionPrevious value: -"Brand names; resolved to IDs via Vinted lookup"New value: +"Brand names to filter by, e.g. [\"Nike\", \"Adidas\"]. Automatically resolved to IDs via search_brands."Input schema / properties / brandIds / descriptionAdded value: +"Numeric Vinted brand IDs from search_brands. Prefer the brand[] parameter for name-based lookup."Input schema / properties / categoryId / descriptionAdded value: +"Category ID from get_categories (e.g. 4 = women's clothing, 5 = men's clothing, 1231 = women's shoes)"Input schema / properties / condition / descriptionAdded value: +"Item condition filter; multiple values are OR-ed together"Input schema / properties / country / descriptionAdded value: +"Vinted country site to search (fr, de, uk, pl, es, nl, be, it, pt, cz, sk, hu, ro, lt, lv, ee, fi, at, se)"Input schema / properties / dateFrom / descriptionPrevious value: -"ISO date string e.g. 2024-01-01"New value: +"Return items listed on or after this date. ISO-8601 format, e.g. \"2024-01-01\""Input schema / properties / dateTo / descriptionAdded value: +"Return items listed on or before this date. ISO-8601 format, e.g. \"2024-12-31\""Input schema / properties / page / descriptionAdded value: +"Page number starting at 1"Input schema / properties / perPage / descriptionAdded value: +"Results per page, 1–96. Defaults to 20."Input schema / properties / priceMax / descriptionAdded value: +"Maximum price in the local currency of the selected country"Input schema / properties / priceMin / descriptionAdded value: +"Minimum price in the local currency of the selected country"Input schema / properties / query / descriptionAdded value: +"Search keywords, e.g. \"Nike Air Max 90\" or \"levi 501 jeans\""Input schema / properties / sizeIds / descriptionPrevious value: -"Size IDs (use get_categories + search_items to discover)"New value: +"Size IDs to filter by. Discover valid IDs by inspecting results from a previous search in the same category."Input schema / properties / sortBy / descriptionAdded value: +"Sort order for results. Defaults to relevance."v1.0.0compare_pricesget_categoriesget_itemget_sellerget_seller_itemsget_trendingsearch_brandssearch_itemsScored across 12 tools
Each tool targets a clearly distinct resource or action: reference lookups (colors, size groups, brands, categories), searching (search_items, search_all_items, trending), item details, seller info, feedback, and price comparison. The only potential confusion is search_items vs search_all_items, but their descriptions explicitly differentiate paginated vs. comprehensive multi-page results.
All tools follow a consistent verb_noun pattern: get_* for retrievals, search_* for searches, compare_* for price comparison. The naming style is uniform and predictable, with no mixed conventions or vague verbs.
12 tools is well-scoped for a marketplace search/browse server. Reference data (colors, size groups, brands, categories), search options, item/seller detail, and price comparison each have a dedicated tool without redundancy.
The surface covers browsing, searching, price comparison, and seller evaluation thoroughly. Minor gaps: no way to resolve a seller by username (only numeric ID), no item URL-to-seller/ID parsing beyond get_item, and no direct item-to-seller relationship exposed if item results omit seller ID.
MCP server for Product Management
MCP Server for an Agent Task Marketplace
