Skip to main content
Glama

List locations

list_locations
Read-onlyIdempotent

Research places with coordinates and ancestor rollups. Two tiers: level "country" or "place" (city, region or site); one item counts under both. Feed a name into search_research_items.location.

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": "list_locations"
  }
}

Input Schema

NameRequiredDescriptionDefault
bboxNo[west, south, east, north]; west > east crosses the antimeridian
nearNoPlaces within km (> 0) of a point; latitude -90..90, longitude -180..180
limitNoDefault 50, max 300
offsetNo
countryNoOne country, exact name or alias, plus its cities
filtersNoResearch-item filters applied before place counts
keywordNoFilter on the place name; every word must match, quote a phrase

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedInput schema / properties / bbox / description
      Previous value: -"[west, south, east, north]"New value: +"[west, south, east, north]; west > east crosses the antimeridian"
    • changedInput schema / properties / keyword / description
      Previous value: -"Substring filter on the place name"New value: +"Filter on the place name; every word must match, quote a phrase"
    • changedInput schema / properties / near / description
      Previous value: -"Places within km of a point"New value: +"Places within km (> 0) of a point; latitude -90..90, longitude -180..180"
  2. Changed1 schema field changed
    • removedInput schema / $schema
      Removed value: -"https://json-schema.org/draft/2020-12/schema"
  3. Changed1 schema field changed
    • addedInput schema / properties / filters / properties / mentions_country
      Added value: +{
      +  "maxLength": 1000,
      +  "type": "string"
      +}
  4. Changed3 schema fields changed
    • removedInput schema / properties / filters / properties / location_id / maximum
      Removed value: -9007199254740991
    • changedInput schema / properties / filters / properties / project_id / anyOf
      Previous value: -[
      -  {
      -    "maxLength": 256,
      -    "type": "string"
      -  },
      -  {
      -    "exclusiveMinimum": 0,
      -    "maximum": 9007199254740991,
      -    "type": "integer"
      -  }
      -]New value: +[
      +  {
      +    "maxLength": 256,
      +    "type": "string"
      +  },
      +  {
      +    "exclusiveMinimum": 0,
      +    "type": "integer"
      +  }
      +]
    • removedInput schema / properties / limit / maximum
      Removed value: -9007199254740991
  5. Changed6 schema fields changed
    • addedInput schema / properties / bbox
      Added value: +{
      +  "description": "[west, south, east, north]",
      +  "items": {
      +    "type": "number"
      +  },
      +  "maxItems": 4,
      +  "minItems": 4,
      +  "type": "array"
      +}
    • changedInput schema / properties / country / description
      Previous value: -"Narrow to one country: the country itself plus its cities/regions"New value: +"One country, exact name or alias, plus its cities"
    • addedInput schema / properties / country / maxLength
      Added value: +1000
    • addedInput schema / properties / filters
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Research-item filters applied before place counts",
      +  "properties": {
      +    "added_since": {
      +      "maxLength": 40,
      +      "type": "string"
      +    },
      +    "collection": {
      +      "maxLength": 1000,
      +      "type": "string"
      +    },
      +    "contributor": {
      +      "maxLength": 1000,
      +      "type": "string"
      +    },
      +    "country": {
      +      "maxLength": 1000,
      +      "type": "string"
      +    },
      +    "genre": {
      +      "maxLength": 1000,
      +      "type": "string"
      +    },
      +    "has_media": {
      +      "type": "boolean"
      +    },
      +    "keyword": {
      +      "maxLength": 1000,
      +      "type": "string"
      +    },
      +    "language": {
      +      "maxLength": 1000,
      +      "type": "string"
      +    },
      +    "location": {
      +      "maxLength": 1000,
      +      "type": "string"
      +    },
      +    "location_id": {
      +      "exclusiveMinimum": 0,
      +      "maximum": 9007199254740991,
      +      "type": "integer"
      +    },
      +    "modified_since": {
      +      "maxLength": 40,
      +      "type": "string"
      +    },
      +    "project_id": {
      +      "anyOf": [
      +        {
      +          "maxLength": 256,
      +          "type": "string"
      +        },
      +        {
      +          "exclusiveMinimum": 0,
      +          "maximum": 9007199254740991,
      +          "type": "integer"
      +        }
      +      ]
      +    },
      +    "research_section": {
      +      "maxLength": 1000,
      +      "type": "string"
      +    },
      +    "resource_type": {
      +      "maxLength": 1000,
      +      "type": "string"
      +    },
      +    "subject": {
      +      "maxLength": 1000,
      +      "type": "string"
      +    },
      +    "university": {
      +      "maxLength": 1000,
      +      "type": "string"
      +    },
      +    "year_from": {
      +      "maximum": 2200,
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    "year_to": {
      +      "maximum": 2200,
      +      "minimum": 0,
      +      "type": "integer"
      +    }
      +  },
      +  "type": "object"
      +}
    • addedInput schema / properties / keyword / maxLength
      Added value: +1000
    • addedInput schema / properties / near
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Places within km of a point",
      +  "properties": {
      +    "km": {
      +      "exclusiveMinimum": 0,
      +      "type": "number"
      +    },
      +    "latitude": {
      +      "type": "number"
      +    },
      +    "longitude": {
      +      "type": "number"
      +    }
      +  },
      +  "required": [
      +    "latitude",
      +    "longitude",
      +    "km"
      +  ],
      +  "type": "object"
      +}
  6. First observed

TDQS

B3.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, idempotent, non-destructive, closed world), so the description's real contribution is the rollup disclosure: one item counts under both a country tier and a place tier, meaning counts are not disjoint and will double-count. That is a non-obvious aggregation trait an agent could easily misread, and it is stated explicitly here.

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 short sentences, front-loaded with the core purpose and followed by the counting nuance and the routing pointer. Nothing is padded, though the opening phrase is compressed to the point of being cryptic and would read better as an explicit 'lists places with coordinates'.

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?

For a seven-parameter, nested-filter, no-output-schema tool, the description covers the aggregation semantics well but says nothing about what a result item contains (name, coordinates, parent chain, count), so an agent cannot anticipate the shape of the response. The phantom "level" tier language also leaves ambiguity about whether tier selection is configurable.

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

Parameters2/5

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

Schema coverage is high (86%) and documents bbox, near, limit, offset, country, filters and keyword, so the schema baseline is 3. But the description describes a "level" of "country" or "place" that does not exist anywhere in the input schema, which can lead an agent to attempt an unsupported argument; the remaining parameters (bbox, near, filters) get no added meaning at all.

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

Purpose3/5

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

"Research places with coordinates and ancestor rollups" is a verb-plus-resource statement, and the two-tier explanation clarifies what a returned place represents. However, "Research places" is an odd verb for a list operation, and the description never plainly says this returns a listing of locations with counts rather than research items, leaving the agent to infer its output from the tier sentence.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The closing line gives one concrete routing cue: if you already have a place name, feed it into search_research_items.location instead. That is genuinely useful, but it only covers the reverse direction; there is no guidance on when to call list_locations itself versus siblings like list_publication_facets or list_institutions, nor any statement about prerequisites or when not to use it.

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.