get_city_statsAggregate figures for one covered city: venue count, modality and access breakdowns, contrast-capable count, and median published prices and plunge temperature. Every median carries its denominator (n) — absent fields are excluded, never treated as zero.
| Name | Required | Description | Default |
|---|---|---|---|
| citySlug | Yes | City slug, e.g. "dallas-tx". Use list_cities to discover. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses important return semantics: medians include denominators, and absent fields are excluded rather than zeroed. This reduces misinterpretation risk, though it doesn't cover invalid-city behavior or response shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler: the first states purpose and contents, the second clarifies denominator and zero-handling semantics. Information is front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only aggregation tool with no output schema, the description is complete: it lists all returned metric groups, explains median denominators, and handles the ambiguous zero case. Nothing required to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema already explains citySlug with an example and points to list_cities. The description adds 'covered city' context but doesn't need to document parameter semantics further; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Aggregate') and names the resource ('figures for one covered city') with a concrete list of outputs. This clearly distinguishes it from sibling tools like get_venue (single venue) and search_venues (search), even though it doesn't name them explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The opening phrase 'Aggregate figures for one covered city' clearly indicates the tool is for city-level statistics rather than venue-level retrieval or discovery. It doesn't explicitly say when not to use it or name alternatives, but the context is unambiguous enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Each tool targets a clearly distinct purpose: detailed city aggregates, dataset freshness metadata, individual venue lookup, city listing, and filtered venue search. There is no meaningful overlap or risk of confusing one tool for another.
All five tool names follow the same snake_case verb_noun pattern: get_, list_, and search_. This makes the tool surface predictable and easy for an agent to navigate.
Five tools is well-scoped for a read-only venue discovery and analytics server. Each tool earns its place and collectively they cover both raw venue lookup and aggregate city-level insights.
The surface covers venue search, venue detail retrieval, city enumeration, city-level statistics, and data freshness checks. For a read-only directory and analytics domain, this is a complete and coherent set with no obvious dead ends.