Sous

Overview Schema Source Related Servers Discussions Admin

Optional: Suggest substitutes

suggest_substitutes

Read-only

Find product substitutes when an item cannot be ordered, matched to intended use, allergens, and purpose. Review each option's compromises before requesting a quote.

Instructions

Good / better / best substitutes for a product that can't be ordered (or for any product).

purpose: what the buyer uses the product for ('coffee', 'recipe: lasagne', 'allergy menu'); substitution exact | ask | allowed. A product the buyer needs exactly (by purpose or the mandate's product_purposes) has no substitutes; for 'ask', any substitute needs the buyer's yes. Pass the same purpose on request_quote items.

Same category, measure and temperature class; keeps the original's dietary claims and the mandate's allergen rules (never relaxed). Each option lists its compromises in plain language and has a live offer. Tell the buyer the compromises, then request_quote for the chosen one with substitute_for=. Another kind of product is never offered: with nothing acceptable, no_safe_substitute says to ask a human and not_offered lists what was ruled out and why. delivery_date null = the next delivery day. With mandate_id it is read-scoped like get_mandate (send your Authorization: Bearer header or agent_token). use: what the product is used for (coffee, whipping, dessert, baking, cooking, drinking, melting, ingredient-in-recipe:). Whipping cream for a dessert needs the same product (another brand whips differently); for coffee any brand will do. Options then carry use_sensitivity, use_ok and use_reason.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "agent_id": "<agent_id>",
      "product_id": "<product_id>",
      "delivery_date": "<delivery_date>",
      "amount": "<amount>"
    },
    "name": "suggest_substitutes"
  }
}

Input Schema

Name	Required	Default
`use`	No
`unit`	No	SALES_UNIT
`limit`	No
`amount`	Yes
`purpose`	No
`agent_id`	Yes
`mandate_id`	No
`product_id`	Yes
`agent_token`	No
`substitution`	No
`delivery_date`	Yes
`avoid_allergens`	No

Output Schema

Name	Required	Description	Default
`options`	Yes
`original`	Yes
`next_step`	No
`considered`	Yes
`constraints`	Yes
`no_safe_substitute`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.0Nov 15, 2026

TDQS

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnly/openWorld annotations, it discloses substantial behavior: dietary claims are preserved and allergen rules are 'never relaxed', only same category/measure/temperature products are considered, each option carries compromises and a live offer, delivery_date null means the next delivery day, and with mandate_id the call is read-scoped like get_mandate with Bearer/agent_token auth. It even describes the no_safe_substitute/not_offered failure shape, which an agent needs before calling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The content is valuable but written as dense, run-on prose where constraints, auth notes and parameter notes are interleaved; only the 'purpose:' and 'use:' labels give any structure. Several ideas (e.g. the same-purpose requirement) recur in different sentences, making it harder to scan than it needs to be.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-parameter, open-world, read-only tool with an output schema, the description covers the domain rules, the safety constraints, auth requirements and the escalation path. Since the output schema exists, the description needn't enumerate return fields, so the remaining gap (undocumented amount/unit/limit semantics) is minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the load and does so for the hardest parameters: 'purpose' (with example values), 'substitution' (exact/ask/allowed and their consequences), 'use' (coffee, whipping, dessert, etc., with the whipping-cream brand example), 'delivery_date' null semantics, and 'mandate_id'/'agent_token' auth behavior. It leaves amount, unit, limit, product_id and avoid_allergens meaning to the schema, which is why this is a 4 rather than a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening line names a specific verb and resource: ranking 'good / better / best substitutes' for a product that can't be ordered, or optionally for any product. It also implicitly separates the tool from the sibling that completes the purchase ('then request_quote for the chosen one'), so an agent can tell which tool finds options and which one commits.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage conditions are explicit: call it when a product can't be ordered or when the buyer wants options, and note that substitution='exact' means there are no substitutes while 'ask' requires buyer consent. It also directs the follow-up (request_quote with substitute_for, or escalate to a human via no_safe_substitute). It stops short of contrasting with sibling tools like get_suggestions or list_offers, so the routing picture is inferred rather than complete.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server