readback

lookup

Read-onlyIdempotent

Resolve a name to the warehouse spelling for metros, carriers, airports, applicant groups, AML rules, counties, years, or quarters, returning candidate choices when a name is ambiguous.

Instructions

Resolve a name to the way the warehouses spell it: a metro (doorstep), a carrier or airport (turnaround), an applicant group, an AML rule or a county (ledger), a year or a quarter. When a name matches more than one entity (Portland, Springfield, Columbus) the server asks the client to choose; a client that cannot be asked receives the candidates with needs_choice set, and must ask the person.

Input Schema

Name	Required	Description	Default
`kind`	Yes
`name`	Yes

Output Schema

Name	Required	Description	Default
`kind`	Yes
`query`	Yes
`resolved`	Yes
`statement`	No		Answers are drawn from the published tables of three portfolio builds by Ajay Mekala: doorstep (public housing data from FHFA, the Census Bureau, HUD, the CFPB and Freddie Mac), turnaround (public flight data from the Bureau of Transportation Statistics, the FAA and OurAirports, with weather from Open-Meteo under CC BY 4.0) and ledger (a fictional bank, Harborline, with public HMDA, CFPB, FDIC and macro series). No person appears in any table, and questions are redacted before a model sees them. Every number is read back to the warehouse before it is shown. This is a portfolio demonstration, not financial, travel or lending advice.
`warehouse`	Yes
`candidates`	Yes
`needs_choice`	Yes	true when the name matches more than one entity and the client could not be asked

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 24, 2026

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already declare the operation read-only, idempotent, and non-destructive, while the description adds meaningful behavioral detail about ambiguous matches: the server prompts the client to choose, and non-interactive clients receive candidates with needs_choice set. This goes beyond the annotations, though it does not describe no-match handling or broader failure behavior.

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?

The definition is two sentences, front-loaded with the core purpose, and every clause contributes useful information about either entity kinds or ambiguity handling. There is no redundant restatement of the schema or annotations.

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?

The tool has only two required parameters, rich annotations, and an output schema, so the description does not need to explain return values. It covers the key ambiguity behavior but leaves sibling-relative usage and no-match behavior implicit, leaving a small completeness gap.

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?

With 0% schema description coverage, the description carries the burden and does add meaning by enumerating the kind values and mapping them to contexts such as metro/doorstep, carrier/airport/turnaround, and county/ledger. It also explains that name is resolved to canonical warehouse spelling and may produce ambiguous candidates, though individual enum values remain only loosely defined.

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

Purpose4/5

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

The description states a specific verb and resource: resolving a name to the canonical warehouse spelling, with several entity kinds enumerated. It is clear what the tool does, though it does not explicitly distinguish itself from sibling tools such as search_catalog or describe.

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?

Usage is implied by the need to resolve names and by the ambiguity-handling guidance, but there is no explicit statement of when to prefer lookup over alternatives or when not to use it. The ambiguity behavior gives useful context but does not fully cover tool selection.

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

Deploy Server