When a desired item is detected as out of stock, trigger the substitution logic: retrieve the item's canonical attributes (category, brand tier, key specifications, price ceiling) to define the substitution search space.
Run a product search filtered to the same category and within the user's defined price tolerance; rank results by a substitution score combining spec similarity, brand preference, and price delta.
Apply hard exclusion rules: do not substitute across incompatible categories (e.g., a 120V appliance for a 240V one), do not exceed a maximum price uplift percentage, and respect any user-specified brand exclusions.
Present the top substitution candidates with a side-by-side comparison of key specs vs the original item; include a confidence score and reason for each suggestion.
If automatic substitution is authorized by the user's policy (e.g., for recurring consumables), apply the highest-ranked substitute and log the substitution event referencing the original item's order context.
Set a restock alert on the original item so the user is notified when it becomes available again, in case they want to revert.
Known gotchas
Specification-based substitution can miss important user preferences not captured in structured attributes (e.g., color, aesthetic, ecosystem compatibility); treat automatic substitution as opt-in and defaulting to human approval.
Prices for in-stock substitutes can be inflated during supply shortages; cap the acceptable price uplift at a configured percentage rather than accepting any in-stock item.
Substitution logic that selects a higher-priced item requires explicit user approval if it exceeds a spending threshold — never automatically upcharge without a confirmed authorization level.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp