Skip to main content
Glama

Closest places by driving time

bl_nearest_by_drive
Read-onlyIdempotent

Ranks nearby places of a chosen category by current-traffic driving time from a point, timing selected candidates and omitting unroutable ones.

Instructions

Rank places of one kind around a point by driving time from it in current traffic, quickest first.

Times a drive to Balad's top candidates places (as bl_nearby lists them), one route call each; unroutable places are left out. For more places without drive times use bl_nearby; details: bl_place.

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_nearest_by_drive"
  }
}

Input Schema

NameRequiredDescriptionDefault
latYesLatitude, e.g. 35.7448.
lngYesLongitude, e.g. 51.3753.
whatYesCategory slug from bl_categories (e.g. pharmacy, gas-station) or free text (e.g. پیتزا).
open_nowNoOnly places open now.
radius_kmNoBox half-width in km (0.5-20).
candidatesNoHow many top places to time (2-8).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv0.2.0
    • changedInput schema / properties / candidates / description
      Previous value: -"How many of Balad's top places to time (2-8)."New value: +"How many top places to time (2-8)."
    • changedInput schema / properties / lat / description
      Previous value: -"Latitude in degrees, e.g. 35.7448."New value: +"Latitude, e.g. 35.7448."
    • changedInput schema / properties / lng / description
      Previous value: -"Longitude in degrees, e.g. 51.3753."New value: +"Longitude, e.g. 51.3753."
    • 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 / radius_km / description
      Previous value: -"Search box half-width in km, e.g. 3 (0.5-20)."New value: +"Box half-width in km (0.5-20)."
    • 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.2/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, non-destructive, idempotent, open-world), and the description adds genuinely non-obvious behavior: one route call per candidate (a latency/cost signal), and "unroutable places are left out," which means results can come back with fewer than `candidates` entries. It does not explain what fields come back or in what units drive time is expressed.

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?

Two sentences, front-loaded with the action and ordering rule, then cost and fallback routing. The telegraphic fragments ("details: bl_place", "one route call each") are efficient but read slightly compressed, which costs a point against a fully polished phrasing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/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 carries the burden of conveying the return shape, and it only implies it (a ranked list with drive times, quickest first). It also omits that results are capped by the geographic bounds in `lat`/`lng` and that traffic makes repeat calls non-identical, which matters for a 6-parameter tool with no output contract.

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 3 is the baseline; the description earns an extra point by clarifying that `candidates` is not a result count but the number of Balad's top-ranked places that get timed, and that ranking re-orders (and can shrink) that pool. That meaning is absent from the schema's "How many top places to time".

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?

"Rank places of one kind around a point by driving time from it in current traffic, quickest first" names a specific verb (rank), the resource (places of one kind), the exact ranking dimension (drive time in current traffic) and the output ordering. It is clearly distinguishable from bl_nearby (same places, no drive times) and bl_route (a single route).

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?

Explicit routing is given: "For more places without drive times use bl_nearby; details: bl_place." That covers the main alternative and the follow-up for place detail. It stops short of stating when NOT to use it (e.g. when more than the 8-candidate cap is needed, or when a known destination should go through bl_route instead), so it is strong but not exhaustive.

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