Skip to main content
Glama

Nearby places by category

bl_nearby
Read-onlyIdempotent

Find nearby pharmacies, restaurants, gas stations, or other place categories around a coordinate, returning address, phone, rating, and straight-line distance.

Instructions

List places of one kind (pharmacy, restaurant, gas station...) around a point, with address, phone and rating.

Balad's own order, each with straight-line distance_km. Free text naming a category (پیتزا) lists that whole category (category says which). Get the point from bl_search. For driving time use bl_nearest_by_drive; for places on a trip bl_along_route; for hours and reviews bl_place with id. Empty: widen radius_km or drop filters.

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": {
      "what": "<what>",
      "lat": "<lat>",
      "lng": "<lng>"
    },
    "name": "bl_nearby"
  }
}

Input Schema

NameRequiredDescriptionDefault
latYesLatitude, e.g. 35.7448.
lngYesLongitude, e.g. 51.3753.
sortNorating = best first, popular = most visited.relevance
whatYesCategory slug from bl_categories (e.g. pharmacy, gas-station) or free text (e.g. پیتزا).
limitNoMax places (1-40).
priceNoRestaurants and cafes only.
open_nowNoOnly places open now.
radius_kmNoBox half-width in km (0.2-20).
min_ratingNoOnly places rated above this.
with_phoneNoOnly places with a phone number.
with_photosNoOnly places with photos.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changedv0.2.0
    • changedInput schema / properties / lat / description
      Previous value: -"Latitude in degrees, e.g. 35.7448."New value: +"Latitude, e.g. 35.7448."
    • changedInput schema / properties / limit / description
      Previous value: -"Max places to return with details (1-40)."New value: +"Max places (1-40)."
    • changedInput schema / properties / lng / description
      Previous value: -"Longitude in degrees, e.g. 51.3753."New value: +"Longitude, e.g. 51.3753."
    • changedInput schema / properties / min_rating / description
      Previous value: -"Only places rated above this, e.g. 4."New value: +"Only places rated above this."
    • changedInput schema / properties / open_now / description
      Previous value: -"Only places Balad marks as open right now."New value: +"Only places open now."
    • changedInput schema / properties / price / description
      Previous value: -"Price level; restaurants and cafes only."New value: +"Restaurants and cafes only."
    • changedInput schema / properties / radius_km / description
      Previous value: -"Search box half-width in km, e.g. 1 (0.2-20)."New value: +"Box half-width in km (0.2-20)."
    • changedInput schema / properties / sort / description
      Previous value: -"relevance (Balad's default), rating (best rated first) or popular (most visited)."New value: +"rating = best first, popular = most visited."
    • changedInput schema / properties / what / description
      Previous value: -"A category slug from bl_categories (e.g. pharmacy, restaurant, gas-station, atm) or free text (e.g. پیتزا, کافه)."New value: +"Category slug from bl_categories (e.g. pharmacy, gas-station) or free text (e.g. پیتزا)."
  2. First observedv0.1.0

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the description doesn't need to restate safety. It adds real behavioral value instead: results follow Balad's own ordering, each carries a straight-line `distance_km`, and free-text categories (پیتزا) expand to the whole category. It stops short of rate limits or pagination/truncation behavior for the 40-result cap.

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?

Purpose is front-loaded in the first sentence and routing guidance follows; no filler sentences. The telegraphic style ("Balad's own order", missing articles) makes a couple of clauses denser than they need to be, but nothing is wasted.

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 an 11-parameter search tool with no output schema, the description covers the return shape (address, phone, rating, distance_km), ordering, and routing to the right sibling. Remaining gaps are minor: what "relevance" sort actually means and whether results are truncated at `limit` silently.

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 baseline is 3, but the description adds meaning beyond the field docs: it explains what happens when `what` is free text rather than a slug, and that `radius_km` widening is the remedy for empty result sets. `sort` semantics and the interaction of filters with the limit cap are left to the schema.

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?

Opens with a specific verb and resource: "List places of one kind ... around a point," and immediately names the returned fields (address, phone, rating). It is clearly distinguished from siblings like bl_place (hours/reviews), bl_nearest_by_drive (driving time) and bl_along_route (trip corridor).

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?

Explicitly names alternatives and the condition that selects each: driving time -> bl_nearest_by_drive, trip places -> bl_along_route, hours and reviews -> bl_place with `id`, and the point itself -> bl_search. It even gives recovery guidance for empty results (widen radius_km or drop filters).

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