The hertwill-mcp server wraps the Hertwill dropshipping API, enabling AI agents to discover products, evaluate margins, manage import lists, and sync products to Shopify/WooCommerce through natural language.
Product Discovery & Evaluation (no API key required)
search_products — Hybrid keyword + semantic search with filters (category, brand, price, stock, EU shipping)
list_products — Filter-driven catalog browsing without a search query
get_product — Full product details including variants and shipping countries
get_brand / get_brand_shipping_price_lists — Brand assets and shipping price lists
evaluate_product — Structured viability scorecard covering margin inputs, shipping, stock, and variant spread
calculate_margin — Pure-math break-even and margin calculator (no network call)
check_health — Server version, API reachability, and rate-limit budget
Import List & Sync (API key required)
list_import_list — View staged products with filtering and pagination
add_to_import_list / remove_from_import_list — Batch-stage or remove up to 50 products by ID
sync_products — Trigger a Shopify/WooCommerce sync with a specified markup multiplier
get_sync_jobs — Check sync job status (queued, syncing, synced, failed)
Pre-built Prompts
8 structured workflow prompts including hw-winner-scan, hw-niche-research, hw-eu-winners, hw-seasonal-picks, hw-competitor-match, hw-margin-check, hw-import-batch, and hw-store-health.
Context Resources 5 readable resources: categories taxonomy, brands taxonomy, product JSON schema, rate limits guide, and EU shipping guide.
Allows triggering product syncs to a Shopify store and checking the status of sync jobs.
Allows triggering product syncs to a WooCommerce store and checking the status of sync jobs.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@hertwill-mcp Find trending pet supplies with at least 60% margin"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol server that wraps the Hertwill dropshipping API — letting any MCP-capable AI agent discover products, evaluate margins, manage an import list, and trigger syncs to Shopify/WooCommerce through natural language.
npx @hertwill/mcpAdd to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"hertwill": {
"command": "npx",
"args": ["@hertwill/mcp"],
"env": {
"HERTWILL_API_KEY": "your-api-key-here"
}
}
}
}Add to .cursor/mcp.json in your project root:
{
"mcpServers": {
"hertwill": {
"command": "npx",
"args": ["@hertwill/mcp"],
"env": {
"HERTWILL_API_KEY": "your-api-key-here"
}
}
}
}Add to .vscode/mcp.json:
{
"servers": {
"hertwill": {
"type": "stdio",
"command": "npx",
"args": ["@hertwill/mcp"],
"env": {
"HERTWILL_API_KEY": "your-api-key-here"
}
}
}
}Each follows the same pattern — add an MCP server entry pointing to npx @hertwill/mcp with the HERTWILL_API_KEY env var. Refer to your client's MCP configuration docs.
No API key? The server starts without one. All 8 discovery tools work immediately — you only need a key for import list and sync operations. Get one at hertwill.com.
Related MCP server: listbee-mcp
Once connected, talk to your AI agent naturally:
"Find me winning EU-shippable kitchen gadgets under €25"
"Evaluate product 4827 — is the margin viable for Facebook ads?"
"Show me trending pet supplies with at least 60% margin potential"
"Add products 1001, 1002, 1003 to my import list"
"What's the health of my store connection?"
Tool | Purpose |
| Hybrid keyword + semantic search with filters (category, brand, price, stock, EU shipping) |
| Browse and filter catalog without a search query |
| Full product detail — variants, shipping regions, descriptions |
| Brand detail incl. marketing material links (logo, cover, downloadable assets) |
| A brand's shipping price lists (coverage tags + per origin→destination rates) |
| Factual viability scorecard: margin inputs, shipping, stock, variant spread |
| Pure-math break-even and margin calculator (no network call) |
| Server version, API reachability, rate limit bucket state |
Tool | Purpose |
| View products in your import list |
| Add products by ID to your import list |
| Remove a product from your import list |
| Check Shopify/WooCommerce sync job status |
| Trigger a product sync to your connected store |
Pre-built workflows the agent can invoke as structured starting points:
Prompt | Purpose |
| Search, evaluate, and calculate margin in one flow |
| Deep-dive a niche with category + brand analysis |
| Find EU-shippable winners with margin analysis |
| Discover products for a specific season |
| Find Hertwill alternatives to a competitor product |
| Single-product margin deep dive |
| Bulk import with mandatory user confirmation |
| Full store diagnostic: auth, API, import list, sync jobs |
Static and dynamic context the agent can read:
Resource | URI |
Categories taxonomy |
|
Brands taxonomy |
|
Product JSON Schema |
|
Rate limits guide |
|
EU shipping guide |
|
Environment Variable | Required | Default | Description |
| No | — | Hertwill API key ( |
| No |
| Log level: |
| No |
| Set to |
Cause: Something is writing to stdout besides JSON-RPC frames. Common culprits: an npm lifecycle script printing a banner, or a stray console.log in a dependency.
Fix: Ensure you're using npx @hertwill/mcp directly (not wrapping it in a shell script that echoes). Logs go to stderr, never stdout.
Cause: The HERTWILL_API_KEY env var is missing, empty, or doesn't match the hw_live_... / hw_test_... format.
Fix: Check the key is set in your MCP client config (not your shell profile — MCP servers don't inherit your shell environment). Get a key at hertwill.com.
Cause: You've hit the Hertwill API rate limit (60 req/min public, 300 req/min authenticated).
Fix: The server handles backoff automatically. Wait for the indicated retry period. If you're hitting limits frequently, batch your requests — use hw-import-batch instead of individual add_to_import_list calls.
# 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 validateThe validate script includes four security gates that run in CI:
check:key-reads — process.env.HERTWILL_API_KEY accessed only in src/config.ts
check:key-leakage — no full-length API key values in the source tree
check:boundaries — import boundary enforcement between layers
audit — pnpm audit --audit-level=high passes with zero high-severity CVEs
Runtime: Node.js >= 20.11, ESM-only
MCP SDK: @modelcontextprotocol/sdk ^1.29
Validation: Zod v4
HTTP: Native fetch + openapi-fetch (typed, 6 KB)
Rate limiting: Bottleneck (60/min public, 300/min authenticated)
Retry: p-retry with exponential backoff + jitter
Logging: Pino to stderr (stdout reserved for JSON-RPC)
Build: tsup (ESM bundle with shebang)
Testing: Vitest + MSW + in-process MCP client
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
