Search local-shop and ship-to-home products by US ZIP and get a JENNi checkout link.
Scored across 5 tools
get_product and search_catalog have nearly identical descriptions and overlapping purposes (both return canonical product facts), leaving the boundary between direct lookup and filtered search somewhat unclear. find_stores, get_buying_options, and start_checkout are clearly distinct steps in the purchase flow, so overlap is limited to the product-facts pair.
All five tools follow a consistent snake_case verb_noun pattern: find_stores, get_buying_options, get_product, search_catalog, start_checkout. Verb choice varies appropriately (find/search/get/start) without breaking the convention.
Five tools cover discovery, product facts, buying options, and checkout without redundancy or bloat. Each tool earns its place in the buyer journey.
The surface covers the discovery-to-checkout lifecycle (find stores, search/get products, get buying options, start checkout). Minor gaps exist around post-purchase operations like order status or cart management, but core purchase workflows are handled.
Read-only shop directory by name. A listing proves no stock, price, delivery or checkout eligibility. Use search_catalog for product facts without store filters; it does not verify stock, price or delivery. Then call get_buying_options with the exact product_id, zip, quantity and fulfillment_mode. After the buyer chooses a returned offer with is_eligible_checkout true, use its store_id with start_checkout for direct checkout. An offer explicitly marked fulfillment concierge may also use start_checkout for a hosted request handoff even when that flag is false. Retain the exact buying context. A handoff does not reserve stock, create a durable quote or complete a purchase.
| Name | Required | Description | Default |
|---|---|---|---|
| zip | No | 5-digit US ZIP code: searches the shops within 15 miles of it first, then the national list. Pass it for any shop outside San Antonio. | |
| name | Yes | Shop name or part of it, e.g. "Cheeky Monkey". | |
| limit | No | Shops to return (default 10). | |
| market | No | Market key, e.g. san-antonio-tx. Used when no zip is given. |
| Name | Required | Description |
|---|---|---|
| name | Yes | |
| stores | Yes | |
| partial | Yes | True when not every listed shop could be compared. |
| location | No | |
| next_step | No | Present when no shop matched. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds the crucial caveat that a listing proves no stock, price, delivery or checkout eligibility, plus handoff non-reservation semantics. Much of the remaining behavioral text concerns downstream tools rather than this one, so it is not fully self-focused.
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 purpose is front-loaded and efficient, but the middle section drifts into start_checkout and concierge handoff rules that are not this tool's concern. Several sentences describing sibling behavior dilute rather than sharpen this definition.
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 description supplies the surrounding buying flow and eligibility caveats. It is broadly complete for a discovery tool, though the downstream checkout detail is more than find_stores itself requires.
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 zip, name, limit and market are already documented, including the 15-mile-then-national behavior and default limit. The description adds no parameter detail beyond the schema, so baseline 3 applies.
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?
"Read-only shop directory by name" gives a specific verb and resource, and the second sentence bounds the result. It also explicitly contrasts with search_catalog (product facts without store filters), so the agent can place it against siblings immediately.
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 states when to use this tool (store lookup by name), names the alternative search_catalog and its condition, and sketches the exact downstream chain (get_buying_options then start_checkout). Exclusions and prerequisites are explicit rather than inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read verified buying options for the exact product, destination, quantity and fulfillment mode. Empty offers mean no options verified for this request, not that the product does not exist. Choose an eligible store, then start_checkout with the same context; the buyer approves and pays in hosted checkout.
| Name | Required | Description | Default |
|---|---|---|---|
| zip | Yes | ||
| quantity | Yes | ||
| product_id | Yes | ||
| fulfillment_mode | Yes |
| Name | Required | Description |
|---|---|---|
| product | Yes | |
| requested_context | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and non-open-world, so the bar is lower. The description still adds real behavior: 'Empty offers mean no options verified for this request, not that the product does not exist' and that the buyer approves and pays in hosted checkout, clarifying this tool never charges.
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 the critical empty-result caveat, then the next step. No filler and no repetition of 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?
An output schema exists so return values need no explanation, and annotations cover the safety profile. The description covers the ambiguous empty-result case and the handoff to start_checkout; only the parameter-level formats (5-digit zip, quantity bounds, mode semantics) are left entirely to the schema, which is acceptable.
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; it maps each parameter to a concept (exact product, destination, quantity, fulfillment mode). However it adds no format or constraint detail beyond the schema's pattern/length/enum/range fields, so it is adequate but not compensatory.
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 (Read) and resource (verified buying options) plus the exact scope qualifiers: product, destination, quantity and fulfillment mode. It also pre-empts the most common confusion by distinguishing an empty result from a non-existent product, which separates it from get_product/search_catalog.
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 explicit workflow guidance ('Choose an eligible store, then start_checkout with the same context'), so the agent knows this feeds checkout. It does not state when NOT to use it versus find_stores or search_catalog, but the ordering is clear enough to route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Complete canonical product facts, read-only. Nullable titles, empty images/offers and unknown stock remain visible. Discovery never authorizes checkout; completion is unavailable. Store filters are rejected; postal context never filters facts. Use search_catalog for product facts without store filters; it does not verify stock, price or delivery. Then call get_buying_options with the exact product_id, zip, quantity and fulfillment_mode. After the buyer chooses a returned offer with is_eligible_checkout true, use its store_id with start_checkout for direct checkout. An offer explicitly marked fulfillment concierge may also use start_checkout for a hosted request handoff even when that flag is false. Retain the exact buying context. A handoff does not reserve stock, create a durable quote or complete a purchase.
| Name | Required | Description | Default |
|---|---|---|---|
| zip | No | Optional echoed caller context only; never filters facts. | |
| product_id | Yes | ||
| postal_code | No | Optional echoed caller context only; never filters facts. |
| Name | Required | Description |
|---|---|---|
| mode | Yes | |
| items | Yes | |
| exhausted | Yes | |
| next_cursor | Yes | |
| offer_policy | Yes | |
| contract_version | Yes | |
| catalog_authority | Yes | |
| requested_context | Yes | |
| snapshot_semantics | Yes | |
| source_observed_at | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only/idempotent/non-destructive, and the description adds substantial behavior beyond them: nullable titles and empty images/offers stay visible, unknown stock remains visible, postal context is echoed but never filters, and the handoff path does not reserve stock, create a durable quote or complete a purchase.
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?
Front-loaded with purpose and constraints, and every sentence carries routing or state semantics. It is dense for a single-resource getter and drifts into describing downstream start_checkout eligibility (including the concierge handoff carve-out), which is useful but borders on belonging in those tools' own descriptions.
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 is unnecessary, and the description covers the remaining agent-critical gaps: nullability of titles, visibility of empty images/offers/unknown stock, no-facts-filtering by postal or store, and the full downstream handoff chain with its non-reserving guarantee.
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 67% and both zip and postal_code are already documented in the schema as non-filtering echoed context, so the description's 'postal context never filters facts' largely repeats structured data. product_id remains undocumented in both places — the description only says to pass the 'exact product_id' without adding format, length or lookup semantics. Baseline 3 for partial coverage 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?
Opens with a specific verb+resource and scope: 'Complete canonical product facts, read-only.' It then explicitly positions itself against siblings ('Use search_catalog for product facts without store filters') so an agent can distinguish it from search_catalog, get_buying_options and start_checkout without opening any 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?
Gives explicit when-to-use routing: search_catalog when store filters are not needed, get_buying_options next with exact context, start_checkout only after an offer with is_eligible_checkout true. It also states exclusions ('Store filters are rejected', 'Discovery never authorizes checkout'), so the boundary conditions are unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Complete canonical product facts, read-only. Nullable titles, empty images/offers and unknown stock remain visible. Discovery never authorizes checkout; completion is unavailable. Store filters are rejected; postal context never filters facts. Use search_catalog for product facts without store filters; it does not verify stock, price or delivery. Then call get_buying_options with the exact product_id, zip, quantity and fulfillment_mode. After the buyer chooses a returned offer with is_eligible_checkout true, use its store_id with start_checkout for direct checkout. An offer explicitly marked fulfillment concierge may also use start_checkout for a hosted request handoff even when that flag is false. Retain the exact buying context. A handoff does not reserve stock, create a durable quote or complete a purchase.
| Name | Required | Description | Default |
|---|---|---|---|
| zip | No | Optional echoed caller context only; never filters facts. | |
| gtin | No | ||
| brand | No | ||
| limit | No | ||
| query | No | Optional title, brand, UPC or GTIN keyword. Omit to enumerate approved root catalog facts. | |
| cursor | No | Confidential opaque upstream continuation; forward unchanged with the same selectors and limit. | |
| store_id | No | Unsupported for catalog facts; nonempty store filters are rejected. | |
| store_ids | No | Empty normalizes to absent; store filtering is unsupported. | |
| product_id | No | ||
| postal_code | No | Optional echoed caller context only; never filters facts. |
| Name | Required | Description |
|---|---|---|
| mode | Yes | |
| items | Yes | |
| exhausted | Yes | |
| next_cursor | Yes | |
| offer_policy | Yes | |
| contract_version | Yes | |
| catalog_authority | Yes | |
| requested_context | Yes | |
| snapshot_semantics | Yes | |
| source_observed_at | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, yet the description still adds real behavioral facts: nullable titles, empty images/offers and unknown stock remain visible, store filters are rejected, and postal context never filters facts. The bulk of workflow behavior it describes (checkout/handoff) belongs to other tools, which dilutes but does not invalidate the disclosure.
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?
A large share of the text describes get_buying_options and start_checkout behavior rather than this tool, making it bloated and off-scope. The opening fragments ('Complete canonical product facts, read-only') are terse but not informative, and the workflow digression should be trimmed or relocated.
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 description does surface the key constraints (no store filtering, no stock/price verification). However, with 10 parameters at 60% description coverage and no parameter-level guidance for the core selectors (query, gtin, brand, cursor), the definition leaves gaps an agent must resolve from the schema alone.
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 60% with 10 parameters, so the schema carries most of the load. The description restates schema-level facts (zip/postal are echoed context only, store filters unsupported) rather than adding new meaning, and says nothing about query, gtin, brand, limit, cursor or product_id. This matches the baseline 3 when structured fields do the heavy lifting.
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 frames the tool as returning 'complete canonical product facts, read-only' and later 'product facts without store filters,' which is a clear enough verb+resource. It partially distinguishes itself by excluding store filtering and by positioning itself as the discovery step before get_buying_options, though it never addresses find_stores or get_product directly. The title 'Search local shops' is misleading against a tool that explicitly rejects store filters, but the description corrects that.
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 gives an explicit when-to-use ('Use search_catalog for product facts without store filters') plus exclusions ('it does not verify stock, price or delivery', 'Store filters are rejected') and names the downstream alternative chain (get_buying_options, then start_checkout). It stops short of naming the sibling to use for store-scoped lookups (find_stores), so routing is only partly complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call when the shopper has chosen to buy: the exact product_id (a variant's when it has sizes or colours), the store_id of an offer with is_eligible_checkout true or fulfillment concierge, a quantity and their ZIP. Re-checks the offer at that quantity and returns checkout_url: JENNi checkout with that item added to the shopper's basket, where they enter email, name, address and card and see delivery, tax and the total; nothing is charged until they place the order. For a concierge offer it returns a product page handoff, where the shopper sets quantity and the page checks request availability. This handoff does not create a durable quote, reserve stock or purchase anything. After get_buying_options retain its exact quantity, ZIP and fulfillment_mode.
| Name | Required | Description | Default |
|---|---|---|---|
| zip | Yes | 5-digit US ZIP code the order is delivered to, e.g. 78205. | |
| quantity | Yes | How many (default 1). | |
| store_id | Yes | store_id of an offer with is_eligible_checkout true, or a concierge offer. | |
| product_id | Yes | The exact item: a variant's product_id when it has variants. | |
| fulfillment_mode | Yes | Retain the mode chosen from get_buying_options. |
| Name | Required | Description |
|---|---|---|
| item | No | |
| kind | Yes | |
| quantity | No | |
| next_step | Yes | |
| store_name | No | |
| unit_price | No | The shelf price the page shows; checkout states the total. |
| checkout_url | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotentHint=true and destructiveHint=false, so the safety profile is covered, and the description adds genuinely new context: nothing is charged until the order is placed, and the concierge handoff creates no durable quote, reserves no stock, and purchases nothing. It does not cover auth needs or failure behavior when the re-check fails.
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?
Front-loaded with the trigger and effect, and every sentence carries information (trigger, required inputs, return semantics, handoff caveat, sequencing). The middle sentence is dense and run-on, but there is no 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-required-param tool with two distinct outcomes, the description covers both branches, the sequencing with get_buying_options, and the non-charging guarantee; an output schema exists so return-format detail is not needed. Only the failure path when the offer re-check fails 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 100%, so the baseline is 3, but the description adds meaning beyond the schema by tying parameters to the source call ('retain its exact quantity, ZIP and fulfillment_mode' from get_buying_options) and clarifying the variant product_id requirement. This cross-parameter guidance goes past the field-level schema text.
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 states a specific trigger ('Call when the shopper has chosen to buy') and the concrete effect: re-checks the offer at that quantity and returns a checkout_url with the item added to the shopper's basket. It also distinguishes the two output paths (JENNi checkout vs. a concierge product-page handoff), so an agent can tell it apart from siblings like get_buying_options 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?
It gives an explicit trigger condition and preconditions: store_id must be an offer with is_eligible_checkout true or a concierge offer, and the inputs should be retained from get_buying_options. It stops short of naming an explicit 'do not use when' case, but the when-to-use context is unambiguous.
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.
find_stores1 field changedOutput schema / properties / stores / items / properties / alias_store_idsAdded value: +{
+ "description": "Other store rows of this same physical shop, for display; search_catalog with the store_id covers them (PAS expands it).",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}find_storesget_buying_optionsget_productsearch_catalogstart_checkoutFind flower arrangements, check US florist delivery by ZIP and date, get a purchase link + pricing
Search direct grocery storefronts and create product-link pickup handoffs.
Search live store shelves, verify delivery windows, and run instant AI agent checkouts.
AI shopping gateway for product search, inventory, carts, and merchant-hosted checkout.
Add one secure layer between your agents and this server.