Skip to main content
Glama

Cities

dt_cities
Read-onlyIdempotent

Find a city's slug and numeric ID to build doctor search filters and suggestions, with optional medical speciality filtering to list cities that have matching doctors.

Instructions

Find a city's slug (for search filters) and numeric id (for dt_suggest); main cities first.

With speciality only main cities are listed. Next: dt_search_doctors(city=slug), dt_neighborhoods.

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

Input Schema

NameRequiredDescriptionDefault
limitNoMax cities.
queryNoPart of Persian name or slug, e.g. 'شیراز'.
specialityNoOnly cities with doctors of this speciality (with counts), e.g. 'cardiologist'.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changedv0.5.0
    • removedInput schema / properties / query / anyOf
      Removed value: -[
      -  {
      -    "maxLength": 50,
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • changedInput schema / properties / query / description
      Previous value: -"Part of the city name in Persian or the slug, e.g. 'شیراز'."New value: +"Part of Persian name or slug, e.g. 'شیراز'."
    • addedInput schema / properties / query / maxLength
      Added value: +50
    • addedInput schema / properties / query / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedInput schema / properties / speciality / anyOf
      Removed value: -[
      -  {
      -    "maxLength": 80,
      -    "pattern": "^[a-z0-9][a-z0-9_-]*$",
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • changedInput schema / properties / speciality / description
      Previous value: -"Only cities that have doctors of this speciality, with counts, e.g. 'cardiologist'."New value: +"Only cities with doctors of this speciality (with counts), e.g. 'cardiologist'."
    • addedInput schema / properties / speciality / maxLength
      Added value: +80
    • addedInput schema / properties / speciality / pattern
      Added value: +"^[a-z0-9][a-z0-9_-]*$"
    • addedInput schema / properties / speciality / type
      Added value: +[
      +  "string",
      +  "null"
      +]
  2. Changed5 schema fields changedv0.3.0
    • removedInput schema / properties / limit / title
      Removed value: -"Limit"
    • removedInput schema / properties / query / title
      Removed value: -"Query"
    • removedInput schema / properties / speciality / title
      Removed value: -"Speciality"
    • removedInput schema / title
      Removed value: -"dt_citiesArguments"
    • changedOutput schema / (root)
      Previous value: -{
      -  "additionalProperties": true,
      -  "title": "dt_citiesDictOutput",
      -  "type": "object"
      -}New value: +null
  3. First observedv0.1.0

TDQS

A4.4/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 the safety profile is covered. The description adds behavior beyond that: results are ordered main-cities-first, and the `speciality` filter changes which cities appear. It does not discuss pagination behavior or the maximum result cap on the returned set, though the limit parameter is self-explanatory.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, zero filler, with the core purpose front-loaded before the caveat and the chaining hint. Every clause carries usable information.

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?

With no output schema, the description still identifies the returned fields (slug, numeric id) and the ordering, which is enough to call and consume the tool. A minor gap is that it doesn't mention what accompanies the speciality filter beyond the counts noted in the schema.

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 description coverage is 100%, so the params are already documented, making 3 the baseline. The description earns an extra point by clarifying the semantic side effect of `speciality`: only main cities are returned when it is used, which the schema does not state.

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?

The definition states a specific verb and resource: find a city's slug (for search filters) and numeric id (for dt_suggest). It also scopes the result ordering (main cities first), so an agent can tell what it returns and which downstream tools consume the values, setting it apart from siblings like dt_suggest and dt_search_doctors.

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?

The description names concrete next steps (dt_search_doctors(city=slug), dt_neighborhoods) which gives an agent a clear chaining pattern. It also explains a filtering nuance: with `speciality` only main cities are listed. It does not explicitly say when not to use it or name an alternative city-lookup tool, so it stops short of full routing guidance.

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