Provides tools for searching listings, fetching items and sellers, comparing prices across countries, and retrieving trending feeds on the Vinted marketplace.
Give your AI assistant access to Vinted — search, compare prices, and track sellers across 19 countries.
Vinted has no public API. This package bridges that gap — it lets AI assistants talk directly to Vinted via the Model Context Protocol.
Connect it to Claude, Cursor, or any MCP-compatible assistant and just ask:
"Find me a North Face jacket under €60 in Germany, good condition or better"
"Compare prices for Air Jordan 1s across France, Italy and the UK"
"What is seller #123456 currently selling? Anything under €20?"
The AI figures out which filters to use, calls Vinted, and gives you a real answer — no searching, no filtering, no tabs.
Also ships as a CLI tool and TypeScript library for direct use.
Related MCP server: qontoctl
An MCP server, CLI tool, and TypeScript library for the Vinted secondhand marketplace. No official API — it bootstraps a session cookie from the public catalog page and calls the private JSON API the Vinted web app uses internally.
🤖 MCP server — plug into Claude, Cursor, or any AI assistant with MCP support
🖥️ CLI tool — pipe results, watch for new listings, compare prices from your terminal
📦 TypeScript library — import opSearch, opCompare, etc. directly in your code
npm install -g @googlarz/vinted-clientOr run without installing:
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 tableCommand | Description |
| Search listings with full filter support |
| Get full item detail |
| Seller profile |
| Items a seller has for sale |
| Price comparison across countries |
| Look up brand IDs by name |
| Browse the category tree |
| Newest / trending listings |
| Inspect session cookies (for troubleshooting) |
Flag | Description |
| Output format (default: |
| Country code (see below) |
| HTTP/HTTPS proxy (also: |
| Disable response cache |
Flag | Description |
| Price range |
| Brand names (auto-resolved to IDs) |
| Comma-separated brand IDs |
| Category ID ( |
| Comma-separated size IDs |
|
|
|
|
| Date range filter (YYYY-MM-DD) |
| Walk pages and collect all results |
| Cap for |
| Poll every N seconds for new listings (default 60s) |
fr de uk it es nl pl pt be at lt cz sk hu ro hr fi dk se
Drop Vinted into any MCP-compatible AI assistant (Claude, Cursor, etc.).
Add to claude_desktop_config.json:
{
"mcpServers": {
"vinted": {
"command": "npx",
"args": ["-y", "@googlarz/vinted-client/mcp"]
}
}
}claude mcp add vinted -- npx -y @googlarz/vinted-client/mcpTool | Description |
| Search with full filter support |
| Item detail by ID or URL |
| Seller profile |
| Active listings for a seller |
| Multi-country price comparison |
| Trending listings |
| Brand lookup |
| Category tree |
Example prompts once connected:
"Find me Nike Air Max 95s under €70 in Germany, size 43, very good condition"
"Compare prices for a North Face puffer jacket across France, Germany and Italy"
"Watch seller #987654 and tell me when they list something under €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 has no public API. This library:
Bootstraps a session by hitting vinted.{cc}/catalog and capturing the auth cookies the Vinted frontend sets.
Calls the private JSON API (/api/v2/...) with those cookies, mimicking browser request headers.
Re-bootstraps automatically on 401 — tokens expire, the library recovers silently.
Rate-limits per country with a token bucket (configurable burst + refill) to avoid 429s.
Caches responses with LRU+TTL — 60s for search results, 1h for static data like categories.
Falls back to HTML scraping for item pages blocked by DataDome (JSON-LD + regex extraction).
Prefetches 3 pages concurrently in opSearchAll to maximise throughput within the rate-limit budget.
If Vinted blocks your IP (common on cloud VMs and CI), set a proxy:
VINTED_PROXY_URL=http://user:pass@proxy:8080 vinted search "nike"
# or
vinted search "nike" --proxy http://user:pass@proxy:8080Standard HTTPS_PROXY / HTTP_PROXY env vars are also respected.
Variable | Description |
| HTTP/HTTPS proxy URL |
| Cache TTL in ms (default |
| Requests per second per country (default |
| Token bucket burst size (default |
| Set to |
Node.js ≥ 18
Optional: playwright + puppeteer-extra-plugin-stealth for --browser / VINTED_BROWSER=1 mode
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 |
|---|---|---|---|
| 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. | |
| limit | No | Number of listings to sample per country. Higher values give more accurate statistics (max 96). |
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 |
|---|---|---|---|
| country | No | Country site to fetch categories for (category IDs are consistent across countries) | fr |
| query | No | Optional keyword filter on category name, e.g. "shoes" or "dress" |
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 |
|---|---|---|---|
| itemId | No | Numeric Vinted item ID, e.g. 5678901234 | |
| url | No | Full Vinted item URL, e.g. "https://www.vinted.fr/items/5678901234-nike-air-max". Country is inferred from the URL automatically. | |
| country | No | Country site (required when using itemId; inferred automatically when url is provided) | |
| browser | No | Use headless browser for retrieval. Requires optional Playwright deps; only needed for items blocked by bot detection. |
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 |
|---|---|---|---|
| sellerId | Yes | Numeric Vinted user ID, visible in profile URLs: vinted.fr/member/12345-username | |
| country | No | Country site where the seller is registered | fr |
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 |
|---|---|---|---|
| sellerId | Yes | Numeric Vinted user ID (visible in profile URLs: vinted.fr/member/12345-username) | |
| country | No | Country site where the seller is registered | fr |
| limit | No | Reviews per page, 1–100 | |
| page | No | Page number starting at 1 |
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 |
|---|---|---|---|
| sellerId | Yes | Numeric Vinted user ID | |
| country | No | Country site where the seller is registered | fr |
| limit | No | Items per page, 1–100 | |
| page | No | Page number starting at 1 |
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 |
|---|---|---|---|
| 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 | |
| limit | No | Number of trending items to return, 1–96 |
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 |
|---|---|---|---|
| query | Yes | Search keywords | |
| country | No | Vinted country site to search | fr |
| priceMin | No | Minimum price in local currency | |
| priceMax | No | Maximum price in local currency | |
| brandIds | No | Numeric brand IDs from search_brands | |
| brand | No | Brand names; automatically resolved to IDs | |
| categoryId | No | Category ID from get_categories | |
| sizeIds | No | Size IDs to filter by | |
| colorIds | No | Color IDs to filter by. Use get_colors to discover all available color IDs. | |
| condition | No | Item condition filter | |
| sortBy | No | Sort order | |
| 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 |
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 |
|---|---|---|---|
| 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 |
| limit | No | Maximum number of brand results to return |
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 |
|---|---|---|---|
| query | Yes | Search keywords, e.g. "Nike Air Max 90" or "levi 501 jeans" | |
| 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 |
| priceMin | No | Minimum price in the local currency of the selected country | |
| priceMax | No | Maximum price in the local currency of the selected country | |
| brandIds | No | Numeric Vinted brand IDs from search_brands. Prefer the brand[] parameter for name-based lookup. | |
| brand | No | Brand names to filter by, e.g. ["Nike", "Adidas"]. Automatically resolved to IDs via search_brands. | |
| categoryId | No | Category ID from get_categories (e.g. 4 = women's clothing, 5 = men's clothing, 1231 = women's shoes) | |
| 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. | |
| 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. | |
| condition | No | Item condition filter; multiple values are OR-ed together | |
| sortBy | No | Sort order for results. Defaults to relevance. | |
| perPage | No | Results per page, 1–96. Defaults to 20. | |
| page | No | Page number starting at 1 | |
| dateFrom | No | Return items listed on or after this date. ISO-8601 format, e.g. "2024-01-01" | |
| dateTo | No | Return items listed on or before this date. ISO-8601 format, e.g. "2024-12-31" |
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. Dates show when Glama detected each change.
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_itemsEach tool has a clearly distinct purpose: search, item details, seller info, categories, brands, trending, and price comparison. Even the two search tools are differentiated by pagination scope.
All tool names follow a consistent verb_noun pattern with lower_case and underscores, e.g., get_categories, search_items, compare_prices.
With 10 tools, the set is well-scoped for a Vinted marketplace server, covering all essential operations without being bloated.
The tool surface covers search, item retrieval, seller profiles and feedback, categories, brands, trending, and cross-country price comparison, leaving no obvious gaps for browsing and analysis.
MCP server for Product Management
MCP Server for an Agent Task Marketplace
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/googlarz/vinted-mcp-cli'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
