Skip to main content
Glama

Shortlist vendors for an event

shortlist_vendors
Read-onlyIdempotent

A shortlist for one event: for each service asked for, the most bookable New York area vendors that serve the area and event type. Ranked by how directly a consumer can act (book online, instant quote or open dates, quote form), then by fit with the budget, bookability score and price. Pass guests and hours to get each vendor's published rate worked out for the event (estimate). Use it to answer "help me find a DJ, caterer and florist for a 120-guest bar mitzvah in Brooklyn, 4 hours, under $3,000 each".

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": {
      "categories": "<categories>"
    },
    "name": "shortlist_vendors"
  }
}

Input Schema

NameRequiredDescriptionDefault
areaNoOptional area: NYC (any of the five boroughs), Manhattan, Brooklyn, Queens, Bronx, Staten Island, Long Island, Westchester, North Jersey or Central Jersey, or New Jersey for both; a county or town also works (Bergen County, Hoboken, Monmouth County). Omit for the whole New York area.
hoursNoOptional length of the event in hours. Per-hour prices (some DJs, photographers, bands) are worked out for this long.
needsNoOptional things the vendor must offer, as its own website states: "kosher", "halal" (caterers), "MC", "lighting", "photo booth" (DJs, bands), "second shooter" (photographers), "second videographer", "comes to you" (hair and makeup), "staff" (caterers), "delivery and setup" (florists, cakes).
guestsNoOptional number of guests. Per-guest prices (catering, cakes) are worked out for this many.
budget_usdNoOptional budget per service, US dollars. Vendors whose published starting price fits come first.
categoriesYesThe services needed, in plain words, e.g. ["DJ", "photographer", "florist"]. Up to 6.
event_typeNoOptional event type in plain words: "wedding", "bar mitzvah", "sweet 16", "birthday", "corporate holiday party", "baby shower".
per_categoryNoVendors per service, 1 to 10.

Output Schema

NameRequiredDescriptionDefault
areaYes
hoursNo
groupsYes
guestsNo
cite_asNoAgent Bookability Index by The Runup (index.therunup.ai)
budget_usdYes
event_typeYes
how_rankedYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / area / description
      Previous value: -"Optional area: NYC (any of the five boroughs), Manhattan, Brooklyn, Queens, Bronx, Staten Island, Long Island, Westchester, North Jersey or Central Jersey. Omit for the whole New York area."New value: +"Optional area: NYC (any of the five boroughs), Manhattan, Brooklyn, Queens, Bronx, Staten Island, Long Island, Westchester, North Jersey or Central Jersey, or New Jersey for both; a county or town also works (Bergen County, Hoboken, Monmouth County). Omit for the whole New York area."
    • addedInput schema / properties / needs
      Added value: +{
      +  "anyOf": [
      +    {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Optional things the vendor must offer, as its own website states: \"kosher\", \"halal\" (caterers), \"MC\", \"lighting\", \"photo booth\" (DJs, bands), \"second shooter\" (photographers), \"second videographer\", \"comes to you\" (hair and makeup), \"staff\" (caterers), \"delivery and setup\" (florists, cakes).",
      +  "title": "Needs"
      +}
  2. Changed6 schema fields changed
    • addedInput schema / properties / guests
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Optional number of guests. Per-guest prices (catering, cakes) are worked out for this many.",
      +  "title": "Guests"
      +}
    • addedInput schema / properties / hours
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "number"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Optional length of the event in hours. Per-hour prices (some DJs, photographers, bands) are worked out for this long.",
      +  "title": "Hours"
      +}
    • addedOutput schema / $defs / Estimate
      Added value: +{
      +  "properties": {
      +    "basis": {
      +      "description": "How it was worked out, e.g. \"$35 per guest x 120 guests\".",
      +      "title": "Basis",
      +      "type": "string"
      +    },
      +    "total_usd": {
      +      "description": "Starting price for this event, US dollars, from the vendor's published rate.",
      +      "title": "Total Usd",
      +      "type": "number"
      +    }
      +  },
      +  "required": [
      +    "total_usd",
      +    "basis"
      +  ],
      +  "title": "Estimate",
      +  "type": "object"
      +}
    • addedOutput schema / $defs / VendorCard / properties / estimate
      Added value: +{
      +  "anyOf": [
      +    {
      +      "$ref": "#/$defs/Estimate"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Only in shortlists: the published starting price worked out for this event's guests or hours. A starting point, not a quote."
      +}
    • addedOutput schema / properties / guests
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Guests"
      +}
    • addedOutput schema / properties / hours
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "number"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Hours"
      +}
  3. Added

TDQS

A4/5.0
Behavior4/5

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 credit goes to what the description adds: the exact ranking formula and the fact that guests/hours cause published rates to be recomputed as estimates. It also grounds the data in what vendors state on their own websites, which tells the agent how much to trust the figures. It does not say what happens when no vendor matches a category or area.

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?

The core behavior and ranking logic are front-loaded, and the closing example sentence earns its place by making the tool's routing obvious. The middle sentences are dense and slightly run-on, packing ranking tiers and estimation behavior into long clauses, but nothing is redundant.

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?

With 8 parameters, full schema coverage, annotations, and an output schema, the description covers the remaining burden well: scope of area, ranking, and estimate computation. Gaps are minor, such as behavior on unrecognized categories or an empty result set, and the presence of an output schema removes the need to document return values.

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 100%, so the baseline is 3, but the description goes further by explaining the causal link between parameters and output: guests and hours drive per-guest and per-hour rate estimation, and budget_usd reorders results by published starting price rather than filtering them out. That distinction between ranking and filtering is real semantic value the schema does not convey.

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

Purpose4/5

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

States a specific verb and resource: it returns a shortlist of the most bookable vendors per requested service in the New York area, and spells out the ranking order (actionability, then budget fit, bookability score, price). That is far more than a restatement of the name. It never names search_vendors or compare_vendors as the alternative, so sibling differentiation is left implicit.

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?

Gives a concrete triggering scenario ('help me find a DJ, caterer and florist for a 120-guest bar mitzvah in Brooklyn, 4 hours, under $3,000 each') plus the instruction to pass guests and hours when per-event rates are wanted. It does not state when NOT to use it or point at search_vendors for a plain unranked lookup, so the exclusion side is missing.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources