Skip to main content
Glama

places_in_view

What is over THERE: given a position and the direction the user is facing, the places inside that cone, and whether the ground and the buildings in between let them actually be seen. Use this for "what is that over there", "is there a pub in that direction", "what am I looking at". Use nearby_places instead when the question is about what is NEAR a point rather than what is in a direction. Provide lat, lon, bearing_deg (degrees CLOCKWISE FROM TRUE NORTH: 0 north, 90 east, 180 south, 270 west) and at least one of category or name; category=building reaches named buildings. Optional fov_deg is the FULL width of the cone (default 60, so 30 degrees either side), radius_m the range (default 1000, max 5000), eye_height_m the observer's eye height (default 1.6). Each result carries distance_m, bearing_deg, a signed angular_offset_deg (negative left, positive right), a spoken direction, and a visibility block. READ THE VISIBILITY BLOCK BEFORE SAYING ANYTHING: clear means nothing in the data stands in the way, occluded names what does (a hill, or a building with its height), and unknown means NO check could run: with unknown say you cannot tell, never that it is visible. Read basis too: terrain-only in a town means hills were checked and buildings were not, which is weak. A non-zero out_of_sector means there ARE matching places nearby, just not in that direction, so say that rather than "nothing nearby". coverage names the datasets that answered and caveat is the standing limit: visibility is modelled from maps, not observed, and trees, walls, scaffolding and weather are not in it. Requires the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY).

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": {
      "lat": "<lat>",
      "lon": "<lon>",
      "bearing_deg": "<bearing_deg>"
    },
    "name": "places_in_view"
  }
}

Input Schema

NameRequiredDescriptionDefault
latYesLatitude of the observer in decimal degrees (−90 to 90).
lonYesLongitude of the observer in decimal degrees (−180 to 180).
nameNoA place name or brand to look for. At least one of `category` and `name` is required.
limitNoMaximum number of results (1–25, default 5).
fov_degNoFull width in degrees of the cone centred on `bearing_deg` (1–360, default 60, so 30 degrees either side). The FULL width, not the half angle.
categoryNoThe kind of place to look for, from the same vocabulary `nearby_places` uses ("cafe", "pub", "fuel", "charging_station" …). Use "building" to ask what a named building over there is. At least one of `category` and `name` is required.
radius_mNoMaximum straight-line range in metres (1–5000, default 1000).
bearing_degYesWhich way the observer is facing, in degrees **clockwise from true north** (0 = north, 90 = east, 180 = south, 270 = west). Required: this tool answers "what is over there", and "there" has to point somewhere.
eye_height_mNoHeight of the observer's eye above the ground in metres (0–500, default 1.6, a standing adult). A driver's eye is nearer 1.2 m.
visible_onlyNoWhen true, return only places whose visibility verdict is `clear`. Default false, which returns everything in the cone WITH its verdict, usually the better answer, because "it is there but you cannot see it from here" is worth saying.

Output Schema

NameRequiredDescriptionDefault
caveatYesThe standing caveat: visibility here is modelled, not observed.
resultsYesPlaces inside the cone, best first: everything visible before everything unchecked before everything occluded, and within each of those, nearest and most nearly dead-ahead first.
coverageYesOne sentence naming which datasets the visibility verdicts were actually checked against. Worth repeating when a verdict is being relied on.
out_of_sectorNoHow many otherwise-matching places were dropped for lying outside the cone. Non-zero means there ARE matching places near the observer, just not in the direction they are facing, so say that rather than "nothing nearby".

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / $defs / PlaceInView / required
      Previous value: -[
      -  "name",
      -  "label",
      -  "lat",
      -  "lon",
      -  "distance_m",
      -  "bearing_deg",
      -  "angular_offset_deg",
      -  "direction",
      -  "visibility"
      -]New value: +[
      +  "name",
      +  "label",
      +  "lat",
      +  "lon",
      +  "categories",
      +  "distance_m",
      +  "bearing_deg",
      +  "angular_offset_deg",
      +  "direction",
      +  "visibility"
      +]
  2. Added

TDQS

A4.8/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so: it discloses the visibility verdict vocabulary (clear/occluded/unknown) and the instruction not to claim visibility under `unknown`, the `basis` field's weakness (terrain-only in a town), the `out_of_sector` semantics, `coverage`, the standing caveat (modelled from maps, no trees/walls/weather), and the gateway auth requirement.

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?

Dense and front-loaded: the core question it answers comes first, then routing guidance, then required inputs, then interpretation rules for the result block. It is long, and a few clauses (repeated defaults for fov_deg and radius_m) duplicate the schema, but nearly every sentence carries operational instruction.

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?

For a 10-parameter tool with an output schema, the description covers what the schema cannot: how to read the visibility block before speaking, how to interpret `basis` and `out_of_sector`, and what datasets and limits apply. An agent has everything needed to call it correctly and to phrase the answer honestly.

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 adds interpretation: it restates the clockwise-from-true-north bearing convention, clarifies that `fov_deg` is the FULL cone width (30 degrees either side of a 60 default), notes `category=building` reaches named buildings, and states the at-least-one-of category/name constraint. Most of this also lives in the schema, which caps it below 5.

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?

States a specific verb-and-resource: places inside a view cone from a position plus a facing direction, including whether intervening ground and buildings permit visibility. It explicitly contrasts itself with `nearby_places` (direction vs proximity), so an agent can distinguish it from the sibling without opening a schema.

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?

Gives concrete trigger utterances ("what is that over there", "is there a pub in that direction") and an explicit when-not with the named alternative: use `nearby_places` when the question is about what is near a point rather than in a direction. Nothing is left to inference about routing.

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