An MCP server that lets Claude inspect a WooCommerce store, with optional write access for stock and order status.
List and retrieve recent orders with filters for status, date range, and customer.
List and retrieve products with price, stock, categories, SKUs, and variation details.
List registered customers by name, email, or username.
Generate low-stock reports for tracked products, optionally including variations.
Generate sales summaries with order count, revenue, refunds, average order value, and top sellers.
When WC_ALLOW_WRITES=true, update product or variation stock quantities and change order statuses.
Read store metadata such as URL, WooCommerce/WordPress versions, currency, timezone, and whether writes are enabled via the woocommerce://store resource.
Read-only (optionally write-enabled) access to a WooCommerce store's REST API v3: list and fetch orders, products (including variations), customers, low-stock reports and sales summaries with revenue, refunds, average order value and top sellers. With writes enabled it can set stock quantities and change order statuses, and it exposes a store resource with the store URL, WooCommerce/WordPress versions, currency, timezone and write flag.
Click on "Deploy 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., "@woocommerce-mcp which products are below 5 in stock?"
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.
An MCP server that lets Claude look at a WooCommerce store: orders, products, customers, stock and a sales summary. It talks to the WooCommerce REST API v3 with a normal API key, and it is read-only unless you switch writes on.
Works with Claude Desktop, Claude Code and any other MCP client that can start a stdio server.
Once the server is connected you can ask things like:
"What sold best in the last 30 days?"
"Which products are below 5 in stock?"
"Show me the open orders from ann@example.com"
"Set the stock of SKU MUG-1 to 40" (only with writes enabled)
Claude picks the tool, the server answers with trimmed JSON, Claude explains it.
Related MCP server: mcp-woocommerce
Python 3.10 or newer.
pipx install git+https://github.com/inmanjeffrey89-cell/woocommerce-mcpor
pip install git+https://github.com/inmanjeffrey89-cell/woocommerce-mcpEither one puts a woocommerce-mcp command on your PATH. python -m woocommerce_mcp does the same thing.
In the WordPress admin go to WooCommerce > Settings > Advanced > REST API and click "Add key". Pick a user who can manage the store, set permissions to Read, and generate. Copy the consumer key and consumer secret right away; WooCommerce shows the secret once.
Read is enough for everything except update_stock and update_order_status. If you want those, create the key with Read/Write and set WC_ALLOW_WRITES=true (see below).
The store needs to be on HTTPS. WooCommerce only accepts key and secret authentication over HTTPS.
The server reads four environment variables:
Variable | Required | Meaning |
| yes | Store address, the WordPress root, for example |
| yes | Consumer key from the REST API page |
| yes | Consumer secret from the REST API page |
| no |
|
If one of the required variables is missing the server prints which one and exits instead of starting.
Add this to claude_desktop_config.json (Settings > Developer > Edit Config):
{
"mcpServers": {
"woocommerce": {
"command": "woocommerce-mcp",
"env": {
"WC_URL": "https://shop.example",
"WC_CONSUMER_KEY": "ck_xxx",
"WC_CONSUMER_SECRET": "cs_xxx"
}
}
}
}Claude Desktop does not read your shell PATH. If it reports that the server failed to start, replace "woocommerce-mcp" with the full path that which woocommerce-mcp prints.
claude mcp add woocommerce \
-e WC_URL=https://shop.example \
-e WC_CONSUMER_KEY=ck_xxx \
-e WC_CONSUMER_SECRET=cs_xxx \
-- woocommerce-mcpAdd -e WC_ALLOW_WRITES=true to enable writes. Check with claude mcp list.
Read tools (always on):
Tool | What it does |
| Recent orders, with filters for status, a date range and a customer id, email or name |
| One order with line items, addresses, totals, shipping, refunds and the customer note |
| Products with price and stock, filtered by search term, SKU, stock status or category |
| One product; variable products come with their variations |
| Registered customers, searchable by name, email or username |
| Everything at or under a stock threshold, plus items marked out of stock |
| Order count, revenue, refunds, average order value and top sellers for a date range |
Write tools (need WC_ALLOW_WRITES=true):
Tool | What it does |
| Set a product's or variation's stock quantity |
| Change an order's status |
With writes off, both tools answer with a short message saying writes are disabled and do nothing else.
There is also one resource, woocommerce://store, with the store URL, WooCommerce and WordPress versions, currency, timezone and whether writes are enabled.
Money values are passed through as strings exactly as WooCommerce reports them, with the currency code alongside. Dates go in and come out in the store's timezone.
update_order_status triggers the same side effects as changing the status in the admin: customer emails go out, stock can be released or restocked, and payment gateways may react. Setting an order to refunded only changes the label; no money moves. update_stock overwrites the quantity and turns on stock management for that product.
Leave writes off unless you need them, and when you turn them on, read what Claude proposes before you approve the tool call.
Bad keys, missing orders, a store that is not reachable, rate limits and non-JSON responses all come back as a plain sentence that says what went wrong and, where it helps, what to check. Claude sees the sentence, not a stack trace.
sales_summary and low_stock_report walk the whole result set 100 items at a time. They stop at 5,000 items and set truncated: true in the result when that happens.
low_stock_report checks published products. Pass include_variations: true to also check each variable product's variations; that costs one request per variable product. With it off, variable_products_unchecked says how many variable products were skipped.
Products and variations with stock management off have no quantity to compare, so they never count as low. They show up in untracked_count, with up to 10 of them in untracked_examples, so a "nothing is low" answer can say what it couldn't check.
The woocommerce://store resource reads system_status, which WooCommerce only shows to users who can manage the store. With a more limited key you still get the URL and the writes flag.
git clone https://github.com/inmanjeffrey89-cell/woocommerce-mcp
cd woocommerce-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
ruff check .The tests mock every HTTP call, so they run without a store. To try the read tools against a real store, export the three variables and run:
python scripts/smoke_live.pyIt prints what each read tool returns and never writes anything.
MIT. See LICENSE.
One order in full: line items, addresses, totals, shipping, refunds and the customer note.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the scope of the payload (line items, addresses, totals, refunds, customer note), which helps an agent decide whether this call is sufficient, but says nothing about not-found behavior, permissions, or pagination.
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?
One front-loaded sentence that enumerates the payload and stops. No filler, no repetition of the tool name.
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?
An output schema exists, so return values need no prose. For a one-parameter read tool with annotations covering safety, the description is nearly complete; only error/empty-result behavior is unaddressed.
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 0% and the description never mentions order_id, so it adds no parameter meaning. The single required integer named order_id is largely self-explanatory, which keeps this at the minimum-viable 3 rather than lower.
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?
States the resource precisely ('One order in full') and enumerates the returned sections, which implicitly contrasts with the list_orders sibling. It never names a competing sibling explicitly, so a 4 rather than a 5.
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?
Usage is only implied: 'One order in full' suggests fetching detail for a known order_id rather than browsing. There is no explicit when-to-use, no mention of list_orders as the alternative, and no prerequisite (e.g., needing an order_id from a list call).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One product with price, stock and categories. For a variable product the variations are included with their own SKU, price and stock.
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint already covers the safety profile, so the description's job is added context — and it delivers the non-obvious detail that variable products include their variations with separate SKU, price and stock. It omits error/not-found behavior, but goes modestly beyond the annotations.
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 short sentences, front-loaded with the core resource, then the variation caveat. No filler; nothing repeated from structured fields.
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?
An output schema exists, so return shape needn't be explained, and the variation note is a helpful addition. Still, for a lookup tool with a single undocumented ID parameter, the description should say what identifier to supply and what happens when nothing matches.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage and the description never mentions the sole required parameter, product_id, leaving its type meaning (integer product identifier, not SKU or slug) to be guessed. With an undocumented parameter, this falls below the baseline of 3 that a high-coverage schema would earn.
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?
Names the resource (a single product) and enumerates what the caller gets back: price, stock, categories. That implicitly separates it from list_products, though it never names the sibling or states the singular/plural distinction explicitly.
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?
Usage is only implied by 'One product' — an agent can infer this is the single-item fetch paired with list_products, but there is no explicit when-to-use, no mention of what to do without a product_id, and no handling note for missing IDs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Registered customers, optionally matching a name, email or username. Guest checkouts are not customers; find those through list_orders.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| search | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already declares the safety profile, so the bar is lower. The description adds useful domain semantics about what is and is not a customer, but says nothing about pagination behavior or the fact that limit defaults to 20, which matters for a listing tool. Annotations carry most of the behavioral burden here.
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 short sentences, zero waste, with the resource stated first and the exclusion second. The opening is a noun phrase rather than a verb phrase, which costs a little front-loaded clarity.
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?
An output schema exists, so return values need not be explained, and the entity boundary is covered. The only meaningful omission is pagination/limit behavior for a list tool with a default of 20 and no documented maximum.
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 0%, so the description must compensate. It does partially: 'matching a name, email or username' explains what the search parameter matches, which the bare schema does not. The limit parameter, its default and any bound remain completely undocumented in both places.
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 names the resource (registered customers) and the matching dimensions (name, email, username), and the tool name supplies the 'list' verb. It also draws a clear boundary against guest checkouts, distinguishing it from list_orders. Slightly short of 5 because the verb itself is never stated in the prose.
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 explicitly excludes guest checkouts and routes that case to a named sibling (list_orders), which is real when-not guidance. It stops short of a full positive when-to-use statement against list_orders/get_order beyond that one exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent orders, newest first. Filter by status (pending, processing, on-hold, completed, cancelled, refunded, failed, or several comma-separated), a date range (YYYY-MM-DD or ISO 8601), and a customer (numeric customer id, or an email or name to search for).
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | ||
| limit | No | ||
| before | No | ||
| status | No | ||
| customer | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe read, so the description's extra value is the default ordering (newest first) and the filter semantics. It says nothing about result volume, paging behavior, or what happens when a broad filter matches thousands of orders, which matters for a list endpoint defaulting to limit 20.
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 dense sentences with the resource and ordering front-loaded and no filler. The parenthetical enumerations make it long-ish but every clause carries usable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Return shape is covered by the output schema and safety by annotations, so the remaining burden is filter and paging semantics. The filtering is well covered, but with five parameters and a default page size of 20, the absence of any paging guidance leaves a real gap for an agent that will likely need more than one page.
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 0%, so the description must carry parameter meaning and it partly does: it enumerates the eight status values (the schema has no enum) and explains that customer accepts an id, email, or name. However it never maps its "date range" wording to the actual after/before parameters and completely omits limit, leaving pagination semantics undocumented.
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?
"Recent orders, newest first" names the resource and the sort order in one clause, which clearly distinguishes this from get_order. It never names the sibling it defers to, but the list-vs-single distinction is obvious from the wording.
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 filter clauses imply when the tool is useful (browse recent orders, narrow by status/date/customer), but there is no explicit when-to-use/when-not or pointer to get_order for a known id. Usage is inferred rather than guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Products with price and stock. Filter by a search term, an exact SKU, stock_status (instock, outofstock, onbackorder) or a category (id or name).
| Name | Required | Description | Default |
|---|---|---|---|
| sku | No | ||
| limit | No | ||
| search | No | ||
| category | No | ||
| stock_status | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes this is a safe read, so the description only needs to add context. It adds that results include price and stock, which is useful, but says nothing about pagination, default result size, or ordering — relevant for a listing tool with a limit parameter.
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, zero padding. The return fields come first and the filter options follow, so the most decision-relevant information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With annotations covering safety and an output schema covering the return shape, the description supplies the remaining decision-critical details — filter semantics and accepted values. The gap is the undocumented limit parameter and any pagination/filter-combination behavior.
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 0%, so the description must carry the semantics, and it does for four of five parameters: sku is exact, search is a term, stock_status accepts instock/outofstock/onbackorder (enum values the schema lacks), and category accepts an id or a name. Only limit is left undocumented.
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 names the resource (products) and what each result carries (price and stock), plus the filter surface, so the agent knows this is a filtered product listing. It does not explicitly contrast with get_product or low_stock_report, so sibling differentiation is only implied by the plural/filter framing.
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 says what you can filter on, which implies when to reach for this tool, but there is no explicit 'use this when…' guidance, no exclusion against get_product (single product by SKU) or low_stock_report, and no note on whether filters combine.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Published products whose tracked stock is at or below the threshold, plus anything marked out of stock. Walks the whole catalog. Set include_variations to also check each variable product's variations, at the cost of one extra request per variable product.
| Name | Required | Description | Default |
|---|---|---|---|
| threshold | No | ||
| include_variations | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint already declaring safety, the description adds real operational context: it enumerates the entire catalog and that include_variations costs one extra request per variable product. That cost/performance disclosure is exactly the kind of beyond-annotation value expected. It stops short of saying anything about response size or pagination.
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, zero filler, front-loaded with what the report contains before describing scope and the optional parameter's tradeoff. Every clause 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?
An output schema exists, so return-shape explanation isn't needed, and both parameters are covered. What remains thin is the enumeration behavior under large catalogs — 'walks the whole catalog' hints at cost but doesn't address ordering or limits.
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 0%, so the description carries the burden, and it does define both parameters' meaning: threshold as an at-or-below cutoff on tracked stock, and include_variations as per-variation checking with a stated request cost. Only gaps are the default value (5) and that threshold applies only to tracked stock being restated rather than edge-cased.
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?
States a precise resource and filter: published products with tracked stock at/below a threshold plus out-of-stock items, and adds the scope 'walks the whole catalog.' An agent can immediately distinguish this from the sibling list_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 low-stock framing implies when to use it, but there is no explicit when-to-use/when-not guidance or comparison against sibling tools such as list_products. The include_variations tradeoff is the only conditional guidance offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Order count, revenue, refunds, average order value and the best-selling products between two dates (YYYY-MM-DD, inclusive). Counts orders in the given statuses. Walks every matching order, so a wide range takes several requests.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | ||
| after | Yes | ||
| before | Yes | ||
| status | No | completed,processing |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful non-structured behavior: the tool walks every matching order, so a wide date range spans multiple requests — a real performance/cost signal. It stops short of noting auth or result caching, so a 4 rather than 5.
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 short sentences, front-loaded with the returned metrics, then the counting rule, then the performance caveat. Every sentence provides distinct information and nothing is repeated from schema or annotations.
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?
An output schema exists, so return values need no explanation, and the date/status semantics plus the multi-request caveat cover the main risks. The only gap is the undefined 'top' parameter, which leaves the agent guessing how to control the best-seller list length.
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 0%, so the description must carry parameter meaning. It explains after/before as inclusive YYYY-MM-DD dates and clarifies that status filters counted orders, but the 'top' parameter (default 10) is never mentioned or defined, leaving one of four parameters undocumented in both places.
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 names the exact metrics returned (order count, revenue, refunds, AOV, best-selling products) over a dated range, which is a concrete verb+resource statement. It implicitly distinguishes itself from list_orders by being an aggregate report, but never names a sibling explicitly.
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?
Inclusive date semantics and the status filter scope ('Counts orders in the given statuses') imply how to use it, and the note that a wide range takes several requests warns against over-broad calls. However, it never states when to prefer this over list_orders or another report, leaving the choice to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change an order's status (pending, processing, on-hold, completed, cancelled, refunded, failed). WooCommerce runs its usual side effects, such as emailing the customer. Setting refunded only relabels the order; it does not send money back. Needs WC_ALLOW_WRITES=true.
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | ||
| order_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: it discloses that WooCommerce side effects fire, specifically customer emails, and that setting 'refunded' does not move money — a genuinely consequential behavioral detail. The write-flag prerequisite is also surfaced, which annotations alone would not reveal.
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?
Four short sentences, front-loaded with the action and its valid values, then the side-effect warning, then the caveat, then the prerequisite. Every sentence supplies information an agent needs to call this safely.
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 two-parameter mutation with an output schema and full annotation coverage, the description supplies exactly the missing pieces: valid values, side effects, the refund semantics trap, and the write gate. Nothing needed to invoke it correctly is absent.
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 0% schema description coverage and no enum on the status property, the description carries the load by listing all seven valid statuses, which is the key semantic gap. order_id is left undefined (format, whether it accepts IDs vs keys), so a small gap remains.
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?
States a specific verb and resource ('Change an order's status') and immediately enumerates the exact target values, which distinguishes it from the read-only siblings list_orders/get_order and from update_stock. An agent can tell what this does without opening the schema.
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 a clear operational precondition ('Needs WC_ALLOW_WRITES=true') and the 'refunded only relabels' caveat, which steers an agent away from using it for actual refunds. It does not explicitly name an alternative tool or state when not to use it, but the sibling set makes the boundary obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set a product's stock quantity and turn on stock management for it. Pass variation_id to set one variation of a variable product. Needs WC_ALLOW_WRITES=true.
| Name | Required | Description | Default |
|---|---|---|---|
| quantity | Yes | ||
| product_id | Yes | ||
| variation_id | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint=false, idempotentHint=true, destructiveHint=false, so safety is largely handled. The description still adds two facts annotations cannot express: the call flips stock management ON as a side effect, and it requires the WC_ALLOW_WRITES flag to be enabled. Return behavior is left to the output schema.
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 short sentences, zero filler, with the core action stated first and the conditional parameter note and prerequisite following. Nothing repeats schema or annotation content.
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 3-parameter mutation with an output schema and full annotation coverage, the description supplies the prerequisite and the hidden side effect, which is what an agent most needs. It stops short of explaining edge cases such as quantity 0 versus stock status, or what happens if stock management was already on.
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 0%, so the description must carry the load, and it does the important part: it explains variation_id's purpose (targeting one variation of a variable product) and the word 'Set' implies absolute assignment rather than an increment. product_id and quantity semantics are only implied by their names, leaving minor gaps.
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?
States a specific verb and resource ('Set a product's stock quantity') plus a non-obvious side effect ('turn on stock management for it'). It does not name or distinguish itself from any sibling, though the siblings are all reads (list_products, get_product, low_stock_report), so the write/read split is inferable rather than stated.
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?
Gives conditional guidance for one parameter ('Pass variation_id to set one variation of a variable product') and a prerequisite ('Needs WC_ALLOW_WRITES=true'). It never says when to prefer this over low_stock_report or get_product, and offers no when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_orderget_productlist_customerslist_orderslist_productslow_stock_reportsales_summaryupdate_order_statusupdate_stockScored across 9 tools
List/get pairs on orders and products are clearly distinct, and the two update tools target different resources. The only real overlap is low_stock_report versus list_products with a stock_status filter, but the threshold-scanning semantics and extra options keep them separable.
Core tools follow a clean verb_noun pattern (list_orders, get_product, update_stock, update_order_status). The two report tools (low_stock_report, sales_summary) break the verb-first convention, but they remain short, readable, and unambiguous.
Nine tools is well within the ideal band and each one maps to a concrete WooCommerce operation (orders, products, customers, stock, sales reporting). Nothing feels padded or redundant.
Read coverage is decent (orders, products, customers, sales), but the surface is thin on writes: no create_order, no update_product for name/price/attributes, and no get_customer detail lookup. Agents hitting those tasks will dead-end.
Run a WooCommerce store from Claude: reports, SEO, prices, stock. You approve every change first.
Ask Claude or ChatGPT about your WooCommerce sales, stock and orders. Safe edits with undo.
Let your AI manage WooCommerce and Shopify stores: products, SEO, descriptions and images.
Manage WordPress blogs and WooCommerce shops from Claude, ChatGPT, Cursor and other MCP apps.