get_rankingOne ranking, citywide or for a single area, ordered by exactly one published number. The method behind that number is returned with it. A ranking exists only where at least ten buildings qualify; below that floor an ordering reads as generated rather than measured. Never present a ranking as exhaustive.
| Name | Required | Description | Default |
|---|---|---|---|
| area | No | Omit for the citywide list. | |
| limit | No | ||
| ranking | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds valuable behavior beyond that: it returns the method behind the number, clarifies that rankings below the ten-building floor are generated rather than measured, and warns that rankings should never be presented as exhaustive.
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?
The description is compact and front-loaded, with the core scope in the first sentence. Every subsequent sentence adds an operational or interpretive constraint; there is no filler or repetition.
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 simple read-mostly tool, the description covers the essential semantics: singular result, area scope, ordering basis, validity threshold, and non-exhaustiveness. The absence of an output schema is somewhat mitigated by stating that the method behind the number is returned, though the exact response shape is left unspecified.
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 only 33%, so the description carries the burden, but it does not explain the limit parameter or the semantic differences among the ranking enum values. It only alludes to the citywide-vs-area distinction, which the schema already partly covers with 'Omit for the citywide list.'
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 states the resource precisely: one ranking, citywide or for one area, ordered by exactly one published number. The singular framing distinguishes it from sibling list_rankings, and the mention of the underlying method clarifies what this tool returns beyond a bare list.
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 description gives clear context for when the tool is appropriate: for a single published ranking with a real underlying number, and only where at least ten buildings qualify. It does not explicitly name list_rankings or list exclusions, but the singular scope and validity floor make the intended use apparent.
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 distinct resource and action: fetch retrieves any full record by id or URL, get_area handles area-level medians, get_building gives building records, get_building_transactions lists underlying transactions, get_city_overview provides citywide scope, get_methodology explains definitions, get_ranking returns a single sorted ranking, get_villa_community focuses on villa communities, list_favorites accesses account-specific data, list_rankings enumerates available rankings, and search resolves names to ids. No two tools have overlapping purposes, even when addressing similar domains (e.g., list_rankings vs. get_ranking are clearly differentiated by singular vs. plural and availability of methods).
All tool names use a consistent lowercase_with_underscores format and follow a clear verb_noun pattern: get_ for retrieving specific entities, list_ for enumerations, search for lookup, and fetch for generic retrieval. This makes the API predictable and easy to navigate.
With 11 tools, the server is well-scoped for a real estate index covering city, areas, buildings, villas, transactions, rankings, methodology, and account favorites. Each tool serves a unique function without unnecessary redundancy, fitting the typical range for a purpose-built data server.
The tool set provides comprehensive coverage for a read-only data server: search, area and building details, transaction histories, citywide overview, rankings and their methods, villa communities, methodology reference, and saved favorites. There are no obvious gaps—users can navigate from search to specific records, drill into transactions, compare rankings, and retrieve the methodology behind any figure.