Skip to main content
Glama

Deals near a place in Singapore

nearby_promotions
Read-onlyIdempotent

Find current promotions closest to a location in Singapore, nearest first, with distance in km. Use when someone asks 'deals near me', 'promotions around Tampines' (pass area: 'Tampines', or coordinates). Pass life_stage / age_range / budget / interests when you know them, e.g. a student near NUS: area 'NUS', life_stage 'student', budget 'low' -> cheap food nearby first.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "nearby_promotions"
  }
}

Input Schema

NameRequiredDescriptionDefault
latNoLatitude, e.g. 1.3521 (or give area instead).
lngNoLongitude, e.g. 103.8198
areaNoInstead of lat/lng: an MRT area, mall or campus name, e.g. 'Tampines', 'Orchard', 'Jewel', 'NUS', 'NTU', 'SMU', 'Ngee Ann Poly'. Unknown names return an error; then pass lat/lng.
sortNonewest (default) = latest announced first. top = best picks: fits the meal, ends soon, has a photo, nearby. for_you = top picks that also fit life_stage / age_range / budget / interests (the default when any of those is given).
whenNoOnly deals usable then, Singapore time, reading each deal's hours (e.g. 'Weekdays 3pm-5pm'). 'dinner tonight' = intent dinner + when tonight.
brandNoBrand name or slug, e.g. 'McDonald's'.
limitNoHow many deals to return (1-50).
queryNoWords to match in brand, deal title, summary or outlet, e.g. 'bubble tea' or 'Jewel'.
budgetNoOptional: low = around S$10 or less, freebies and 1-for-1s first; mid = everyday; high = treats (buffets, staycations) are fine.
intentNoWhat the person wants: breakfast, lunch, dinner, coffee (coffee, bubble tea, desserts), drinks, shopping, fun, money (cards & banks).
statusNolive = on now, ends_today, starting_soon = within 7 days.
categoryNoKind of deal.
trip_endNoOptional YYYY-MM-DD: last day of the visit (with trip_start).
active_onNoOnly deals valid on this Singapore date (YYYY-MM-DD).
age_rangeNoOptional: the person's age range, if known. Used only when life_stage is not given (18_24 leans student, 55_plus leans senior); under_18 also sinks alcohol deals. Not stored.
deal_typeNoe.g. one_for_one for 1-for-1 deals.
interestsNoOptional: what they like. Category keys (food, grocery, shopping, fashion, beauty, health, electronics, home, entertainment, travel, finance, insurance, telco, car, property, education) or finer words (bubble_tea, coffee, desserts, fast_food, buffet, korean, japanese, drinks, movies, kids, fitness, staycation, gadgets). Matching deals rank first.
radius_kmNoSearch radius in km.
life_stageNoOptional: who the deals are for, if you already know it from the conversation (never ask just for this). student, working, family (parents with kids), senior, tourist (visiting Singapore). Ranks fitting deals first, e.g. student = cheap food, bubble tea, student discounts first; hotels, cards and insurance later. tourist = deals a visitor can use (no Singapore bank card, residency or local scheme needed) first, attractions and Changi Airport deals up, and each deal gets tourist_fit {usable: yes|maybe|no, needs}. Not stored.
trip_startNoOptional YYYY-MM-DD (Singapore): first day of a visit or of the dates they care about. With trip_end, only deals valid on at least one of those days are returned.
eligibilityNoOnly deals limited to this group, e.g. student for student-only deals.
exclude_categoriesNoOptional: categories to leave out entirely, e.g. ['travel', 'property'] for someone who said hotels don't interest them.
exclude_eligibilityNoLeave out deals limited to these groups, e.g. ['student'] for someone who is not a student. Each deal's `eligibility` lists its groups (empty = anyone).
include_all_outletsNoAlso return island-wide deals valid at all outlets (marked all_outlets_match), after the nearby ones.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / intent / enum
      Previous value: -[
      -  "breakfast",
      -  "lunch",
      -  "dinner",
      -  "coffee",
      -  "drinks",
      -  "shopping",
      -  "fun",
      -  "money"
      -]New value: +[
      +  "breakfast",
      +  "lunch",
      +  "dinner",
      +  "coffee",
      +  "drinks",
      +  "birthday",
      +  "shopping",
      +  "fun",
      +  "money"
      +]
  2. Changed12 schema fields changed
    • addedInput schema / properties / age_range
      Added value: +{
      +  "description": "Optional: the person's age range, if known. Used only when life_stage is not given (18_24 leans student, 55_plus leans senior); under_18 also sinks alcohol deals. Not stored.",
      +  "enum": [
      +    "under_18",
      +    "18_24",
      +    "25_34",
      +    "35_44",
      +    "45_54",
      +    "55_plus"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / area
      Added value: +{
      +  "description": "Instead of lat/lng: an MRT area, mall or campus name, e.g. 'Tampines', 'Orchard', 'Jewel', 'NUS', 'NTU', 'SMU', 'Ngee Ann Poly'. Unknown names return an error; then pass lat/lng.",
      +  "type": "string"
      +}
    • addedInput schema / properties / budget
      Added value: +{
      +  "description": "Optional: low = around S$10 or less, freebies and 1-for-1s first; mid = everyday; high = treats (buffets, staycations) are fine.",
      +  "enum": [
      +    "low",
      +    "mid",
      +    "high"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / exclude_categories
      Added value: +{
      +  "description": "Optional: categories to leave out entirely, e.g. ['travel', 'property'] for someone who said hotels don't interest them.",
      +  "items": {
      +    "enum": [
      +      "food",
      +      "grocery",
      +      "shopping",
      +      "fashion",
      +      "beauty",
      +      "health",
      +      "electronics",
      +      "home",
      +      "entertainment",
      +      "travel",
      +      "finance",
      +      "insurance",
      +      "telco",
      +      "car",
      +      "property",
      +      "education"
      +    ],
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / interests
      Added value: +{
      +  "description": "Optional: what they like. Category keys (food, grocery, shopping, fashion, beauty, health, electronics, home, entertainment, travel, finance, insurance, telco, car, property, education) or finer words (bubble_tea, coffee, desserts, fast_food, buffet, korean, japanese, drinks, movies, kids, fitness, staycation, gadgets). Matching deals rank first.",
      +  "items": {
      +    "enum": [
      +      "food",
      +      "grocery",
      +      "shopping",
      +      "fashion",
      +      "beauty",
      +      "health",
      +      "electronics",
      +      "home",
      +      "entertainment",
      +      "travel",
      +      "finance",
      +      "insurance",
      +      "telco",
      +      "car",
      +      "property",
      +      "education",
      +      "bubble_tea",
      +      "coffee",
      +      "desserts",
      +      "fast_food",
      +      "buffet",
      +      "korean",
      +      "japanese",
      +      "drinks",
      +      "movies",
      +      "kids",
      +      "fitness",
      +      "staycation",
      +      "gadgets"
      +    ],
      +    "type": "string"
      +  },
      +  "maxItems": 12,
      +  "type": "array"
      +}
    • changedInput schema / properties / lat / description
      Previous value: -"Latitude, e.g. 1.3521"New value: +"Latitude, e.g. 1.3521 (or give area instead)."
    • addedInput schema / properties / life_stage
      Added value: +{
      +  "description": "Optional: who the deals are for, if you already know it from the conversation (never ask just for this). student, working, family (parents with kids), senior, tourist (visiting Singapore). Ranks fitting deals first, e.g. student = cheap food, bubble tea, student discounts first; hotels, cards and insurance later. tourist = deals a visitor can use (no Singapore bank card, residency or local scheme needed) first, attractions and Changi Airport deals up, and each deal gets tourist_fit {usable: yes|maybe|no, needs}. Not stored.",
      +  "enum": [
      +    "student",
      +    "working",
      +    "family",
      +    "senior",
      +    "tourist"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / properties / sort / description
      Previous value: -"newest (default) = latest announced first. top = best picks: fits the meal, ends soon, has a photo, nearby."New value: +"newest (default) = latest announced first. top = best picks: fits the meal, ends soon, has a photo, nearby. for_you = top picks that also fit life_stage / age_range / budget / interests (the default when any of those is given)."
    • changedInput schema / properties / sort / enum
      Previous value: -[
      -  "newest",
      -  "ending",
      -  "nearest",
      -  "top"
      -]New value: +[
      +  "newest",
      +  "ending",
      +  "nearest",
      +  "top",
      +  "for_you"
      +]
    • addedInput schema / properties / trip_end
      Added value: +{
      +  "description": "Optional YYYY-MM-DD: last day of the visit (with trip_start).",
      +  "type": "string"
      +}
    • addedInput schema / properties / trip_start
      Added value: +{
      +  "description": "Optional YYYY-MM-DD (Singapore): first day of a visit or of the dates they care about. With trip_end, only deals valid on at least one of those days are returned.",
      +  "type": "string"
      +}
    • removedInput schema / required
      Removed value: -[
      -  "lat",
      -  "lng"
      -]
  3. Changed1 schema field changed
    • addedInput schema / properties / limit / description
      Added value: +"How many deals to return (1-50)."
  4. First observed

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: results are ordered nearest-first, distances are expressed in km, and profile parameters (life_stage/budget/interests) change ranking rather than filtering. It omits return shape and any note on how limit/radius interact with a large result set.

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?

Three sentences, front-loaded with the core behavior and then usage examples; nothing is padding. The final sentence is a long run-on example that takes a second read, but it is content-bearing rather than filler.

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 24-parameter tool with no output schema, the description covers the main path (location resolution, nearest-first ordering, personalization ranking) adequately, with the schema covering the rest. What is missing is any statement about what a result record contains and how the many optional filters combine, which an agent would need for confident multi-filter calls.

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

Parameters3/5

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

Schema description coverage is 100% with enums on the key filters, so the schema does the heavy lifting and baseline 3 applies. The description does add a little beyond the schema by showing how parameters compose in practice (area + life_stage + budget -> cheap food ranked first), but it does not clarify the interaction between the many overlapping filters such as status, active_on and trip_start/trip_end.

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?

A specific verb+resource plus scope: 'Find current promotions closest to a location in Singapore, nearest first, with distance in km.' The location-bound nature is clear. It stops short of distinguishing itself from siblings like search_promotions or recommend_promotions, which plausibly overlap, so it is clear but not sibling-differentiating.

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 concrete trigger phrasings ('deals near me', 'promotions around Tampines') and shows how to translate a user situation into parameters via the 'student near NUS' example. It provides no when-not guidance and never names an alternative sibling for non-proximity searches, so an agent must infer the boundary against search_promotions/recommend_promotions.

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