propose_price_updatePropose new regular or sale prices for a WooCommerce product or variation, then submit the change for human approval before it is applied.
Propose a new regular and/or sale price (as strings in store currency, e.g. "19.90"). Requires human approval.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | Yes | ||
| product_id | Yes | ||
| sale_price | No | Empty string removes the sale | |
| variation_id | No | ||
| regular_price | No |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare a non-read-only, destructive, open-world mutation, so the description's main added value is the approval gate and the currency-string format with an example. That approval requirement is behavioral context the annotations cannot convey and is important since the agent must know the change is deferred, not immediate. It stops short of saying a pending proposal record is created or how it is later applied.
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, both load-bearing: the first defines the operation and the price format, the second gives the approval constraint. Front-loaded and free of filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter destructive mutation with no output schema, the description covers format and the approval gate but omits what happens to prices that are not supplied, how variations are scoped, whether a proposal handle is returned for apply_proposal, and why reason is mandatory. Adequate to start a call, but an agent would still be guessing on several fields.
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 only 20%, so the schema does little; the description compensates for the two price parameters by specifying store-currency strings and an example format, plus the empty-string semantics carried in the schema. Nothing in the description explains product_id scope, what variation_id selects, or the reason field's role and 5-character minimum, leaving half the parameters 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?
States a specific verb ("Propose") plus the exact resource ("new regular and/or sale price"), which cleanly distinguishes it from the other propose_* siblings such as propose_stock_update or propose_refund. It doesn't explicitly name apply_proposal as the counterpart, so sibling routing is implied rather than spelled out.
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?
"Requires human approval" signals the workflow constraint and implicitly tells the agent this is not a direct write, which is useful context. However, it never states when to use this versus apply_proposal or list_proposals, nor what the preconditions are (e.g. valid product/variation, non-empty reason).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.