AI 어시스턴트에게 Vinted 접근 권한을 부여하세요 — 19개국에 걸쳐 검색, 가격 비교, 판매자 추적을 수행할 수 있습니다.
Vinted는 공개 API를 제공하지 않습니다. 이 패키지는 그 간극을 메워줍니다. Model Context Protocol을 통해 AI 어시스턴트가 Vinted와 직접 대화할 수 있게 해줍니다.
Claude, Cursor 또는 MCP 호환 어시스턴트에 연결하고 다음과 같이 질문해 보세요:
*"독일에서 €60 미만의 노스페이스 재킷을 찾아줘, 상태는 좋음 이상으로"
*"프랑스, 이탈리아, 영국 전역의 에어 조던 1 가격을 비교해줘"
*"판매자 #123456이 현재 무엇을 팔고 있지? €20 미만인 물건이 있어?"
AI가 어떤 필터를 사용할지 파악하고, Vinted에 요청을 보내 실제 답변을 제공합니다. 검색하거나 필터를 걸거나 탭을 전환할 필요가 없습니다.
또한 직접 사용할 수 있는 CLI 도구 및 TypeScript 라이브러리로도 제공됩니다.
Related MCP server: qontoctl
Vinted 중고 마켓플레이스를 위한 MCP 서버, CLI 도구, TypeScript 라이브러리입니다. 공식 API가 없으므로, 공개 카탈로그 페이지에서 세션 쿠키를 부트스트랩하여 Vinted 웹 앱이 내부적으로 사용하는 비공개 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 조회 | |
| 카테고리 트리 탐색 | |
| 최신 / 인기 매물 | |
| 세션 쿠키 검사 (문제 해결용) |
플래그 | 설명 | |
`--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
MCP 호환 AI 어시스턴트(Claude, Cursor 등)에 Vinted를 추가하세요.
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 미만, 사이즈 43, 상태 매우 좋음인 나이키 에어 맥스 95를 찾아줘"
*"프랑스, 독일, 이탈리아 전역의 노스페이스 패딩 재킷 가격을 비교해줘"
*"판매자 #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 프론트엔드가 설정하는 인증 쿠키를 캡처합니다.
비공개 JSON API 호출: 해당 쿠키를 사용하여 브라우저 요청 헤더를 모방하고 (/api/v2/...) API를 호출합니다.
자동 재부트스트랩: 401 오류 발생 시 토큰이 만료된 것으로 간주하여 라이브러리가 자동으로 복구합니다.
국가별 속도 제한: 429 오류를 방지하기 위해 토큰 버킷(구성 가능한 버스트 + 리필)을 사용하여 국가별로 속도를 제한합니다.
응답 캐싱: LRU+TTL을 사용하여 캐싱합니다 (검색 결과 60초, 카테고리 등 정적 데이터 1시간).
HTML 스크래핑 폴백: DataDome에 의해 차단된 상품 페이지의 경우 HTML 스크래핑(JSON-LD + 정규식 추출)으로 대체합니다.
동시 프리페치: opSearchAll에서 3개 페이지를 동시에 프리페치하여 속도 제한 범위 내에서 처리량을 극대화합니다.
Vinted가 IP를 차단하는 경우(클라우드 VM 및 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
선택 사항: --browser / VINTED_BROWSER=1 모드를 위한 playwright + puppeteer-extra-plugin-stealth
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
