一个 Model Context Protocol 服务器，封装了 Hertwill 代发货 API —— 让任何支持 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"
}
}
}
}每个客户端都遵循相同的模式 —— 添加一个指向 npx @hertwill/mcp 并带有 HERTWILL_API_KEY 环境变量的 MCP 服务器条目。请参考您客户端的 MCP 配置文档。
没有 API 密钥？ 服务器可以在没有密钥的情况下启动。所有 6 个发现工具均可立即使用 —— 您仅在进行导入列表和同步操作时才需要密钥。请在 hertwill.com 获取。
Related MCP server: listbee-mcp
连接后，像平时一样与您的 AI 智能体交流：
“帮我找找 25 欧元以下、可发往欧盟的爆款厨房小工具”
“评估产品 4827 —— 其利润率是否适合投放 Facebook 广告？”
“向我展示利润潜力至少在 60% 以上的宠物用品趋势”
“将产品 1001、1002、1003 添加到我的导入列表”
“我的商店连接状态如何？”
工具 | 用途 |
| 带有过滤器（类别、品牌、价格、库存、欧盟发货）的混合关键词 + 语义搜索 |
| 在无需搜索查询的情况下浏览和筛选目录 |
| 完整产品详情 —— 变体、发货区域、描述 |
| 事实性可行性评分：利润率输入、发货、库存、变体分布 |
| 纯数学盈亏平衡和利润率计算器（无网络调用） |
| 服务器版本、API 可达性、速率限制桶状态 |
工具 | 用途 |
| 验证 API 密钥格式和身份验证状态 |
| 查看导入列表中的产品 |
| 按 ID 将产品添加到您的导入列表 |
| 从您的导入列表中移除产品 |
| 检查 Shopify/WooCommerce 同步任务状态 |
| 触发产品同步到您已连接的商店 |
智能体可以作为结构化起点调用的预构建工作流：
提示词 | 用途 |
| 在一个流程中搜索、评估并计算利润率 |
| 通过类别 + 品牌分析深入研究细分市场 |
| 查找带有利润分析的可发往欧盟的爆款产品 |
| 发现特定季节的产品 |
| 查找竞争对手产品的 Hertwill 替代品 |
| 单个产品利润率深度分析 |
| 需要用户确认的批量导入 |
| 完整的商店诊断：身份验证、API、导入列表、同步任务 |
智能体可以读取的静态和动态上下文：
资源 | URI |
类别分类法 |
|
品牌分类法 |
|
产品 JSON Schema |
|
速率限制指南 |
|
欧盟发货指南 |
|
环境变量 | 必需 | 默认值 | 描述 |
| 否 | — | Hertwill API 密钥 ( |
| 否 |
| 日志级别： |
| 否 |
| 设置为 |
原因： 除了 JSON-RPC 帧外，有其他内容正在写入 stdout。常见原因：npm 生命周期脚本打印了横幅，或依赖项中存在多余的 console.log。
修复： 确保直接使用 npx @hertwill/mcp（不要将其包装在回显的 shell 脚本中）。日志应发送到 stderr，绝不要发送到 stdout。
原因： HERTWILL_API_KEY 环境变量缺失、为空，或不符合 hw_live_... / hw_test_... 格式。
修复： 检查密钥是否已在您的 MCP 客户端配置中设置（而不是在您的 shell 配置文件中 —— MCP 服务器不会继承您的 shell 环境）。请在 hertwill.com 获取密钥。
原因： 您已达到 Hertwill API 的速率限制（公共每分钟 60 次请求，已认证每分钟 300 次请求）。
修复： 服务器会自动处理退避。请等待指定的重试周期。如果您频繁达到限制，请批量处理您的请求 —— 使用 hw-import-batch 而不是单独调用 add_to_import_list。
# 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 中运行的四个安全门控：
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/分)
重试： p-retry，带有指数退避 + 抖动
日志记录： Pino 到 stderr (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
