Skip to main content
Glama

Shortlist Pass Local Businesses

by com.shortlistpass
OverviewDiscussionsAdmin

Start an order for a customer

start_order

Creates a short-lived cart for a customer at one Shortlist business and returns a cart_url on the business's own page, where the customer reviews the order and pays through the business's checkout. Input is offering ids (preferred) or item names, and quantities; prices are not accepted. Order by id from get_menu or the stop's menu. If you only have a name, send it as name: when it is unclear or not on the menu, no cart is made and the reply (error "needs_choice") lists each line as matched, choose (options with ids) or not_found (genuinely close items with ids, or none) with a message to read to your user; ask them and resend with the offering_id. The server prices every line from the menu, applies the business's deals and tax, and returns the resulting quote. For businesses with menu_source "event" (food trucks), event_id is required and identifies one upcoming stop; the offering ids accepted are those listed in that stop's menu in the upcoming-events data, and pickup_time is one of that stop's open pickup_slots. A stop whose menu_status is "not_live" is refused. The cart expires in 30 minutes. This tool does not accept payment details or addresses; payment happens on the business's page at the returned cart_url. In the quote, total_before_tip excludes the optional tip, which the customer chooses on the checkout page; quote.tip.note states the business's suggested percentage. agent.name is recorded on the cart and the order so the business can see which assistant helped.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
agentNoThe name of the assistant placing the order, e.g. { "name": "Claude" }. Optional; defaults to "AI assistant".
itemsYes
customerNoCustomer details, if provided; pre-filled on the order sheet
event_idNoA stop id from the upcoming-events results. Required for businesses with menu_source "event".
subdomainYesThe business subdomain, e.g. "nitos"
pickup_timeNoOne of the stop's open pickup_slots, "HH:MM" 24-hour

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedInput schema / properties / items / items / properties / name
      Added value: +{
+  "description": "Only when you have no id: the item's name as your user said it. If it is unclear the reply is error \"needs_choice\" with options (ids) per line; ask your user and resend with the offering_id.",
+  "maxLength": 120,
+  "minLength": 1,
+  "type": "string"
+}
    • changedInput schema / properties / items / items / properties / offering_id / description
      Previous value: -"An offering id from the stop's menu (or from the menu results for a fixed business)"New value: +"An offering id from the stop's menu (or from get_menu for a fixed business). Preferred."
    • changedInput schema / properties / items / items / required
      Previous value: -[
-  "offering_id",
-  "quantity"
-]New value: +[
+  "quantity"
+]
  2. Changed2 schema fields changed
    • changedInput schema / properties / agent / description
      Previous value: -"The name of the assistant placing the order, e.g. { \"name\": \"Claude\" }"New value: +"The name of the assistant placing the order, e.g. { \"name\": \"Claude\" }. Optional; defaults to \"AI assistant\"."
    • changedInput schema / required
      Previous value: -[
-  "subdomain",
-  "items",
-  "agent"
-]New value: +[
+  "subdomain",
+  "items"
+]
  3. Changed7 schema fields changed
    • changedInput schema / properties / agent / description
      Previous value: -"Who you are, e.g. { \"name\": \"Claude\" }"New value: +"The name of the assistant placing the order, e.g. { \"name\": \"Claude\" }"
    • changedInput schema / properties / customer / description
      Previous value: -"What the customer told you; pre-fills the order sheet"New value: +"Customer details, if provided; pre-filled on the order sheet"
    • changedInput schema / properties / event_id / description
      Previous value: -"The stop's id from get_upcoming_events. Required for businesses that sell per stop."New value: +"A stop id from the upcoming-events results. Required for businesses with menu_source \"event\"."
    • changedInput schema / properties / items / items / properties / offering_id / description
      Previous value: -"An id from the stop's menu (or get_menu for a fixed business)"New value: +"An offering id from the stop's menu (or from the menu results for a fixed business)"
    • changedInput schema / properties / items / items / properties / options / description
      Previous value: -"Only the offering's own variant/modifier choices, by value or label"New value: +"The offering's own variant or modifier choices, by option value or label"
    • addedInput schema / properties / items / items / properties / quantity / description
      Added value: +"Whole number, 1 to 100"
    • changedInput schema / properties / pickup_time / description
      Previous value: -"A pickup slot from the stop's pickup_slots, \"HH:MM\" 24h"New value: +"One of the stop's open pickup_slots, \"HH:MM\" 24-hour"
  4. Added

TDQS

A4.8/5.0
Behavior5/5

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

Annotations declare a non-idempotent, non-destructive open-world write, and the description adds substantial context beyond them: 30-minute cart expiry, prices not accepted, no payment details/addresses, the needs_choice error shape (matched/choose/not_found), not_live refusal, and how agent.name is recorded. This is far richer than the annotations alone.

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

Conciseness4/5

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

Front-loaded with the core action and return value, but the body is a dense run-on covering error handling, event flow, and tip semantics; every point is relevant yet the lack of structure makes 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.

Completeness5/5

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

With no output schema, the description still explains the returned quote (total_before_tip excludes tip, quote.tip.note suggests a percentage) and cart_url, and covers required prerequisites (event_id, pickup_time) and failure modes. Nothing an agent needs to invoke it correctly is missing.

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 coverage is 83% (baseline 3), and the description adds real meaning: offering_id is preferred over name, quantities are supplied not prices, event_id identifies one upcoming stop's menu, pickup_time maps to open pickup_slots, and agent.name is recorded on the order. It goes meaningfully beyond the schema for the trickiest parameters.

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 description states a specific verb+resource ('Creates a short-lived cart for a customer at one Shortlist business') and names the concrete return value (cart_url), clearly distinguishing it from siblings like get_menu and get_business.

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

Usage Guidelines5/5

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

It routes the agent explicitly: order by offering_id from get_menu or the stop's menu, else send name:. It states the event-business precondition (event_id required, pickup_time must be an open slot, not_live stops refused) and the recovery path on needs_choice, so the when/when-not is fully covered.

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

All Shortlist Pass Local Businesses toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources