Hertwill 드롭쉬핑 API를 래핑하는 Model Context Protocol 서버입니다. MCP를 지원하는 모든 AI 에이전트가 자연어를 통해 제품을 검색하고, 마진을 평가하며, 가져오기 목록을 관리하고, Shopify/WooCommerce로 동기화를 트리거할 수 있게 합니다.
npx @hertwill/mcp~/Library/Application Support/Claude/claude_desktop_config.json(macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json(Windows)에 추가하세요:
{
"mcpServers": {
"hertwill": {
"command": "npx",
"args": ["@hertwill/mcp"],
"env": {
"HERTWILL_API_KEY": "your-api-key-here"
}
}
}
}프로젝트 루트의 .cursor/mcp.json에 추가하세요:
{
"mcpServers": {
"hertwill": {
"command": "npx",
"args": ["@hertwill/mcp"],
"env": {
"HERTWILL_API_KEY": "your-api-key-here"
}
}
}
}.vscode/mcp.json에 추가하세요:
{
"servers": {
"hertwill": {
"type": "stdio",
"command": "npx",
"args": ["@hertwill/mcp"],
"env": {
"HERTWILL_API_KEY": "your-api-key-here"
}
}
}
}각각 동일한 패턴을 따릅니다. HERTWILL_API_KEY 환경 변수와 함께 npx @hertwill/mcp를 가리키는 MCP 서버 항목을 추가하세요. 사용 중인 클라이언트의 MCP 구성 문서를 참조하세요.
API 키가 없나요? 서버는 키 없이도 시작됩니다. 6가지 검색 도구는 즉시 작동하며, 가져오기 목록 및 동기화 작업에만 키가 필요합니다. hertwill.com에서 키를 발급받으세요.
Related MCP server: listbee-mcp
연결되면 AI 에이전트와 자연스럽게 대화하세요:
"EU 배송이 가능한 25유로 미만의 인기 주방 가젯을 찾아줘"
"제품 4827을 평가해줘 — 페이스북 광고에 적합한 마진인가?"
"최소 60%의 마진 잠재력이 있는 트렌디한 반려동물 용품을 보여줘"
"제품 1001, 1002, 1003을 내 가져오기 목록에 추가해줘"
"내 스토어 연결 상태는 어떤가?"
도구 | 목적 |
| 필터(카테고리, 브랜드, 가격, 재고, EU 배송)를 포함한 키워드 + 의미론적 하이브리드 검색 |
| 검색어 없이 카탈로그 탐색 및 필터링 |
| 전체 제품 상세 정보 — 옵션, 배송 지역, 설명 |
| 사실 기반 실행 가능성 점수표: 마진 입력, 배송, 재고, 옵션 분포 |
| 순수 수학적 손익분기점 및 마진 계산기 (네트워크 호출 없음) |
| 서버 버전, API 도달 가능성, 속도 제한 버킷 상태 |
도구 | 목적 |
| API 키 형식 및 인증 상태 확인 |
| 가져오기 목록에 있는 제품 보기 |
| ID를 사용하여 가져오기 목록에 제품 추가 |
| 가져오기 목록에서 제품 제거 |
| Shopify/WooCommerce 동기화 작업 상태 확인 |
| 연결된 스토어로 제품 동기화 트리거 |
에이전트가 구조화된 시작점으로 호출할 수 있는 사전 구축된 워크플로우:
프롬프트 | 목적 |
| 한 번의 흐름으로 검색, 평가 및 마진 계산 |
| 카테고리 + 브랜드 분석을 통한 틈새 시장 심층 분석 |
| 마진 분석을 포함한 EU 배송 가능 인기 제품 찾기 |
| 특정 시즌을 위한 제품 발견 |
| 경쟁사 제품에 대한 Hertwill 대체품 찾기 |
| 단일 제품 마진 심층 분석 |
| 필수 사용자 확인을 통한 대량 가져오기 |
| 전체 스토어 진단: 인증, API, 가져오기 목록, 동기화 작업 |
에이전트가 읽을 수 있는 정적 및 동적 컨텍스트:
리소스 | URI |
카테고리 분류 |
|
브랜드 분류 |
|
제품 JSON 스키마 |
|
속도 제한 가이드 |
|
EU 배송 가이드 |
|
환경 변수 | 필수 | 기본값 | 설명 |
| 아니요 | — | Hertwill API 키 ( |
| 아니요 |
| 로그 레벨: |
| 아니요 |
| 옵트인 원격 측정 활성화 시 |
원인: JSON-RPC 프레임 외에 다른 무언가가 stdout에 기록되고 있습니다. 흔한 원인: npm 라이프사이클 스크립트가 배너를 출력하거나, 의존성 패키지 내의 console.log가 남아있는 경우.
해결: npx @hertwill/mcp를 직접 사용하고 있는지 확인하세요(echo를 사용하는 쉘 스크립트로 래핑하지 마세요). 로그는 stderr로 전달되며, stdout은 절대 사용하지 않습니다.
원인: HERTWILL_API_KEY 환경 변수가 누락되었거나, 비어 있거나, hw_live_... / hw_test_... 형식이 아닙니다.
해결: MCP 클라이언트 구성에 키가 설정되어 있는지 확인하세요(쉘 프로필이 아님 — MCP 서버는 쉘 환경을 상속받지 않습니다). hertwill.com에서 키를 발급받으세요.
원인: Hertwill API 속도 제한(공용 60회/분, 인증 시 300회/분)에 도달했습니다.
해결: 서버가 자동으로 백오프를 처리합니다. 표시된 재시도 기간까지 기다리세요. 제한에 자주 도달하는 경우, 개별 add_to_import_list 호출 대신 hw-import-batch를 사용하여 요청을 일괄 처리하세요.
# Install dependencies
pnpm install
# Run in development
pnpm tsx src/index.ts
# Run tests (436 tests)
pnpm test
# Build
pnpm build
# Full validation (build + lint + security gates + tests)
pnpm validatevalidate 스크립트에는 CI에서 실행되는 4가지 보안 게이트가 포함되어 있습니다:
check:key-reads — process.env.HERTWILL_API_KEY는 src/config.ts에서만 액세스됨
check:key-leakage — 소스 트리에 전체 길이의 API 키 값이 없음
check:boundaries — 계층 간 가져오기 경계 강제 적용
audit — pnpm audit --audit-level=high가 높은 심각도의 CVE 없이 통과됨
런타임: Node.js >= 20.11, ESM 전용
MCP SDK: @modelcontextprotocol/sdk ^1.29
유효성 검사: Zod v4
HTTP: 네이티브 fetch + openapi-fetch (타입 지정, 6 KB)
속도 제한: Bottleneck (공용 60/분, 인증 시 300/분)
재시도: 지터(jitter)를 포함한 지수 백오프 방식의 p-retry
로깅: stderr로 Pino 출력 (stdout은 JSON-RPC용으로 예약)
빌드: tsup (shebang이 포함된 ESM 번들)
테스트: Vitest + MSW + 인프로세스 MCP 클라이언트
MIT
Stage 1-50 Hertwill products into the authenticated store's import list in a single batch. Pass up to 50 product IDs in a single call. Do NOT call this tool in a loop for individual products. Do NOT use before the user has chosen products (use search_products or list_products) or to push staged products to the store (use sync_products). Returns {added, skipped, import_list_size}. Requires HERTWILL_API_KEY.
| Name | Required | Description | Default |
|---|---|---|---|
| product_ids | Yes | Array of Hertwill product IDs (1-50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the auth requirement (HERTWILL_API_KEY), batch limit (1-50), and return format ({added, skipped, import_list_size}). Does not mention duplicate handling or what 'skipped' means, but overall sufficient for a batch add tool.
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?
Five sentences, front-loaded with purpose, then usage guidelines, then behavioral details. Each sentence earns its place with no redundancy or fluff. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains return values. Covers auth requirement, batch limit, and usage constraints. For a simple one-parameter tool, this is thoroughly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with description 'Array of Hertwill product IDs (1-50)' for the only parameter. Description adds batch context and reintroduces the range, but does not add significant meaning beyond what schema already provides, so 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?
The description clearly states the tool stages 1-50 Hertwill products into the authenticated store's import list in a single batch, with specific verb-resource combination. It distinguishes from siblings like remove_from_import_list, sync_products, and search/list tools by specifying the operation and batch constraint.
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 (after product selection), when not to use (not in a loop, not before selection, not to push to store), and provides alternatives (search_products/list_products for selection, sync_products for pushing). This gives clear context for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pure math utility: given cost, retail, ad spend, and VAT rate, return margin amount, margin %, and break-even ad-spend band. Makes zero API calls. Do NOT use when the user wants a real product evaluation (use evaluate_product) or to find products (use search_products). No auth required.
| Name | Required | Description | Default |
|---|---|---|---|
| cost | Yes | Product cost in EUR | |
| retail_price | Yes | Retail price in EUR | |
| ad_spend | No | Ad spend per unit in EUR | |
| vat_rate | No | VAT rate as decimal |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the tool makes zero API calls and requires no authentication, beyond the actions already implied by the description. Since no annotations are provided, the description fully covers behavioral expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no redundant information. The first sentence explains the tool's purpose and inputs/outputs; the second provides usage guidance. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema or annotations, the description fully explains the tool's behavior (pure math, no API calls, no auth), its inputs, outputs (margin amount, %, break-even band), and when to avoid it. Complete for a simple utility.
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 for parameter descriptions. The description adds value by contextualizing the parameters (cost, retail, ad spend, VAT rate) into the margin calculation and previews outputs, though it does not significantly extend 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?
Clearly states it is a 'Pure math utility' that calculates margin metrics from given inputs, and explicitly distinguishes itself from sibling tools by noting it makes zero API calls and is not for product evaluation or search.
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 says when NOT to use it, providing alternatives (evaluate_product, search_products) and emphasizing it is a pure math utility with no API calls, guiding appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report server version, Hertwill API reachability, and remaining rate-limit budget for both the public (60/min) and authenticated (300/min) buckets. Use for connectivity and capacity diagnostics. Do NOT use to search products (use search_products). No auth required.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. It discloses no auth required and implies read-only behavior. Could explicitly state 'read-only' or 'no side effects' but current text is sufficient.
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 filler. Front-loaded with key outputs, then usage 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 zero parameters and no output schema, the description covers all essential information: purpose, outputs, usage context, and exclusion. Complete for a health-check 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?
No parameters, so dimension is trivially satisfied. Description correctly adds context about what the tool reports without needing parameter docs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description specifies exact outputs: server version, Hertwill API reachability, rate-limit budgets. Verb 'report' plus resource 'health metrics' is clear. Distinguishes from search_products sibling.
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 'Use for connectivity and capacity diagnostics' and provides a negative usage case: 'Do NOT use to search products (use search_products).'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Produce a factual structured viability scorecard for one product — margin inputs, shipping coverage, variant spread, and stock signal. Use when the user wants a comparable decision summary. Do NOT use when the user only wants product details (use get_product), pure margin math (use calculate_margin), or to find candidates first (use search_products). No auth required.
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes | Hertwill product ID | |
| target_retail_price | No | Planned retail price in EUR | |
| ad_spend_per_unit | No | Estimated ad spend per unit in EUR | |
| vat_rate | No | VAT rate as decimal (e.g. 0.21 for 21%) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description indicates a read-only operation (factual scorecard) and no authentication needed. Could mention side effects or rate limits, but overall sufficient for safe invocation.
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 a bullet-like list and clear usage guidelines. Every part is necessary and front-loaded with the core 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?
The description explains what the tool does and the output components, compensating for the missing output schema. It covers main use cases but could mention the return format or that it evaluates exactly one product.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds overall context (scorecard components) but does not augment individual parameter descriptions beyond what the schema offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a strong verb ('Produce') and specifies a unique output (factual structured viability scorecard) with listed components. It clearly distinguishes from siblings by naming alternative tools for different needs.
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 ('comparable decision summary') and when not to use, with named alternatives (get_product, calculate_margin, search_products). Also notes 'No auth required'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return full detail for a single Hertwill product by ID, including variations and shipping coverage (ships_to as ISO country codes). Use when you already have a product ID and need variants or shipping detail. Do NOT use to search (use search_products), browse (use list_products), or score viability (use evaluate_product). Supplier text is wrapped in . No auth required.
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes | Hertwill product ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description discloses key behavioral traits: no auth required, supplier text is wrapped in untrusted tags, and the return includes variations and ISO country codes. Lacks mention of side effects (none expected) or rate limits, but sufficient for a read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, then usage boundaries, then safety note. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter detail-retrieval tool with no output schema, the description covers purpose, usage, result components, and a safety concern. Nothing essential missing.
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?
With 100% schema description coverage, the description need not add much. It correctly implies the parameter is a product identifier but doesn't add new semantic value beyond the schema's description.
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 returns full detail for a single product by ID, including variations and shipping coverage. It explicitly distinguishes from sibling tools by naming search_products, list_products, and evaluate_product.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (when you have a product ID and need variants/shipping) and when not to use (search, browse, score viability), naming specific alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return paginated sync job status for the authenticated store. Use to poll or review previously triggered syncs. Do NOT use to trigger a new sync (use sync_products) or to inspect the import list (use list_import_list). Returns a paginated envelope of {sync_job_id, product_id, status, created_at, finished_at, error}. Requires HERTWILL_API_KEY.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based) | |
| per_page | No | Items per page (max 50) | |
| status | No | Filter by job status |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses it is a read operation, paginated, requires API key, and returns a specific envelope structure. Missing potential details like rate limits but covers essential 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?
Three sentences: purpose, usage guidance, return structure. Each sentence serves a clear role. No redundancy or 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 no output schema and no annotations, the description provides purpose, usage, return format, and auth requirement. Sufficient for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, so description adds little beyond schema. It mentions pagination and filtering but does not elaborate beyond what schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns paginated sync job status for the authenticated store, using specific verbs and resource. It distinguishes from siblings by explicitly naming sync_products and list_import_list as alternatives.
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 (poll/review previous syncs) and when not to use (trigger new sync, inspect import list) with named alternative tools. Provides clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the authenticated store's current Hertwill import list, paginated. Use to audit what's staged for sync. Do NOT use to search the catalog (use search_products), stage new products (use add_to_import_list), or check sync status (use get_sync_jobs). Returns a paginated envelope; ships_to is not in list items — use get_product for shipping. Requires HERTWILL_API_KEY.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based) | |
| per_page | No | Items per page (max 50) | |
| status | No | Filter by sync status | |
| order_by | No | Sort field | |
| order | No | Sort direction |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description discloses pagination behavior, that ships_to is not in list items (redirecting to get_product), and the authentication requirement (HERTWILL_API_KEY). Annotations are absent, so description carries the burden; it adds useful behavioral context beyond the schema, though it does not explicitly state idempotency.
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?
Description is concise (3 sentences), front-loaded with purpose, and each sentence adds value. 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?
Given the tool's complexity (5 optional params, no output schema), the description covers the return format (paginated envelope), a data limitation (ships_to absent), and auth requirement. It is largely complete, though it could mention that the result is filtered by store authentication.
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% parameter description coverage with clear definitions (e.g., page, per_page, status, order_by, order). The description does not add extra semantics to the parameters beyond what the schema already provides, so 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?
Description clearly states the tool returns the authenticated store's current Hertwill import list, paginated. It provides a specific verb ('return') and resource ('import list'), and distinguishes from siblings by stating what it is used for ('audit what's staged for sync') and what it is not for.
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 lists when NOT to use the tool (search_products, add_to_import_list, get_sync_jobs) and names the alternative tools. This provides clear guidance for selecting the correct tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Browse and filter the Hertwill catalog without a search query (category, brand, price range, stock status, shipping region). Use for filter-driven enumeration. Do NOT use when the request has keywords or natural-language intent (use search_products), or when the user wants one product's detail (use get_product). Returns a paginated envelope with structured prices and bucketed stock; ships_to is absent from list items — use get_product for shipping. No auth required.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based) | |
| per_page | No | Items per page (max 50) | |
| min_price | No | Minimum price in EUR | |
| max_price | No | Maximum price in EUR | |
| brand | No | Filter by brand slug | |
| category | No | Filter by category slug | |
| on_sale | No | Filter to on-sale products only | |
| stock_status | No | Filter by stock status | |
| shipping_region | No | Filter by shipping region (e.g. 'EU') | |
| sort_by | No | Sort field | |
| sort_order | No | Sort direction |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses key behaviors: returns a paginated envelope, structured prices and bucketed stock, absence of ships_to in list items (redirecting to get_product), and 'No auth required.' This fully informs the agent of what to expect.
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 concise sentences, front-loaded with the purpose and filter dimensions. Every sentence earns its place: purpose, usage guidelines, and behavioral traits are all covered with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters (none required), no output schema, and no annotations, the description covers purpose, usage guidelines, behavioral transparency (pagination, price structure, stock status, missing field), and parameter context. It is fully complete for a filtered enumeration 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 schema already documents all parameters. The description adds context by grouping parameters as filter-driven and noting that ships_to is missing from list items (a behavioral detail not in schema). This adds marginal value, warranting 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 clearly states the tool's purpose: 'Browse and filter the Hertwill catalog without a search query', specifying the verb (browse and filter) and resource (Hertwill catalog). It distinguishes from siblings by listing filter dimensions and explicitly contrasting with search_products and get_product.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use and when-not-to-use guidance: 'Do NOT use when the request has keywords or natural-language intent (use search_products), or when the user wants one product's detail (use get_product).' This clearly directs the agent to the correct sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove 1-50 products from the authenticated store's import list in a single batch call. Pass IDs in one call rather than looping. Do NOT use to view the current list (use list_import_list) or to add items (use add_to_import_list). Returns {removed, skipped, import_list_size}. Requires HERTWILL_API_KEY.
| Name | Required | Description | Default |
|---|---|---|---|
| product_ids | Yes | Array of Hertwill product IDs (1-50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses batch behavior, return fields ({removed, skipped, import_list_size}), and API key requirement. Lacks details on what 'skipped' means but overall adequate.
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 concise sentences, each adding value: purpose, usage tip, exclusions and returns. Front-loaded with main action, 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?
Covers purpose, usage, constraints, returns, and requirement. No output schema, but return format is described. References siblings effectively. Complete for a simple removal 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%, so baseline is 3. Description adds context like batch size (1-50) and type (IDs) but doesn't go beyond schema semantics significantly.
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?
Clearly states verb (remove), resource (products from import list), and constraints (1-50, batch). Differentiates from siblings by specifying not to use for viewing (list_import_list) or adding (add_to_import_list).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (removal) and when not to (viewing/adding). Provides efficiency tip to pass IDs in one call. Includes authentication requirement (HERTWILL_API_KEY).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Hybrid keyword + semantic search over the Hertwill catalog. Use when the user expresses intent with words or a natural-language query. Do NOT use for filter-only browsing (use list_products) or single-product detail (use get_product). Returns a paginated envelope with items carrying structured price {amount, currency} and bucketed stock; ships_to is not in list items — call get_product for shipping detail. Supplier text is wrapped in . No auth required.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query (keyword or natural language) | |
| page | No | Page number (1-based) | |
| per_page | No | Items per page (max 50) | |
| min_price | No | Minimum price in EUR | |
| max_price | No | Maximum price in EUR | |
| brand | No | Filter by brand slug | |
| category | No | Filter by category slug | |
| on_sale | No | Filter to on-sale products only | |
| stock_status | No | Filter by stock status | |
| shipping_region | No | Filter by shipping region (e.g. 'EU') | |
| sort_by | No | Sort field | |
| sort_order | No | Sort direction |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers behavioral traits: returns a paginated envelope, items have structured price and bucketed stock, ships_to is absent from list items (requiring get_product), supplier text is wrapped in <untrusted_supplier_content>, and no auth is required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (about 5 sentences), front-loaded with purpose, and every sentence provides essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 12 parameters and no output schema, the description covers purpose, usage alternatives, core response structure (pagination, price/stock format, trust wrapping), and a key limitation (shipping detail absent), making it complete for correct tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that the response includes 'bucketed stock' and that 'ships_to' is not in list items (a limitation not obvious from schema alone), slightly exceeding baseline.
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 performs 'Hybrid keyword + semantic search over the Hertwill catalog' and explicitly distinguishes from siblings by specifying when not to use it (filter-only browsing uses list_products, single-product detail uses get_product).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance on when to use (user expresses intent with words or natural-language query) and when not to use (filter-only browsing or single-product detail), and names the alternative tools (list_products, get_product).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trigger a Shopify or WooCommerce sync for one product already staged in the import list, with a specified markup. Use to push a single staged product to the connected store. Do NOT use to check sync progress (use get_sync_jobs); if the product isn't yet staged, call add_to_import_list first. Returns {sync_job_id, product_id, status: "queued", markup_applied}. Requires HERTWILL_API_KEY.
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes | Product ID to sync | |
| default_store_markup | Yes | Markup multiplier (e.g. 2.0 for 100% markup) | |
| currency | No | Target currency code | |
| lang | No | Target language code |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It mentions that the tool triggers a sync, returns specific fields, and requires an API key. However, it does not disclose possible side effects, idempotency, or rate limits, leaving gaps for a mutation tool.
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 gives usage guidance, third notes return and auth. Front-loaded and no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a job-triggering tool with no output schema and no annotations, the description covers purpose, usage conditions, return shape, and auth. Missing error conditions and whether sync replaces or merges, but overall fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The description adds value by explaining the return shape and what the markup parameter does ('with a specified markup'), though currency and lang are not further elaborated beyond their 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 the verb 'Trigger', specifies the resource 'one product already staged in the import list', and distinguishes from siblings by explicitly saying to use get_sync_jobs for progress and add_to_import_list if not staged.
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 when-to-use (product already staged) and when-not-to-use (check progress, use get_sync_jobs; if not staged, call add_to_import_list first). This is excellent guidance for correct tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly defined purpose that does not overlap significantly with others. For example, search_products and list_products are differentiated by query type, and evaluate_product versus calculate_margin serve distinct evaluation needs. No two tools appear to do the same thing.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., add_to_import_list, get_product, search_products). There is no mixing of styles, making the naming predictable and easy to understand.
With 11 tools covering catalog search, import list management, syncing, evaluation, and health checks, the tool count is well-scoped for a product management MCP. Each tool serves a distinct and necessary function without bloat.
The tool set covers the full intended workflow: discovering products (list_products, search_products), retrieving details (get_product), evaluating viability (evaluate_product, calculate_margin), managing the import list (add, list, remove), triggering sync (sync_products), monitoring sync jobs (get_sync_jobs), and checking system health (check_health). There are no obvious gaps for the domain.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Print-on-demand catalog, listings, and fulfillment for AI agents.
Agentic commerce gateway: discovery, search, checkout across Shopify/Woo/Odoo/PrestaShop.
Product search for AI agents: Amazon + Shopify, cart-to-checkout buy path. Pay-per-call, no API key.
Manage your NanoCart store from any AI agent: products, orders, coupons, subscribers, reports.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Hertwill/hw-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
