find_citiesLook up US cities that currently have jobs (prefix match), with job counts. Use when a city name is ambiguous or you need the exact spelling before search_jobs.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | City name prefix, e.g. 'san'. | |
| limit | No | ||
| state | No | Restrict to a state (name or 2-letter code). |
| Name | Required | Description | Default |
|---|---|---|---|
| cities | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to cover safety. It adds meaningful behavioral context by specifying prefix matching, job count inclusion, and the requirement that cities currently have jobs. This is useful information beyond what the annotations say.
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 concise: two sentences, front-loaded with the tool's core behavior, and ends with concrete usage guidance. Every sentence earns its place with 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-only lookup tool with good annotations and an output schema, the description covers the essential behavioral contract: what is returned (matching cities with job counts), how matching works (prefix), and when the tool should be used. No critical operational gaps are apparent.
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?
The schema already describes q and state in reasonable detail, and limit has constraints. The description's 'prefix match' phrasing adds only marginal semantic value over q's schema description. It does not explain how limit behaves or how the state parameter interacts with the city prefix, so the description provides an acceptable but not strong contribution.
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 clearly states the tool's action ('Look up US cities'), its scope ('US cities that currently have jobs'), and key behavior ('prefix match, with job counts'). It also distinguishes itself from the sibling search_jobs tool by explicitly positioning it as a pre-step to verify spelling before job search.
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 explicitly says 'Use when a city name is ambiguous or you need the exact spelling before search_jobs', which provides clear contextual guidance. It does not include a full when-not-to-use section or explicitly name alternatives beyond the reference to search_jobs, so it falls just short of a 5.
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 has a clear, distinct responsibility: searching jobs, fetching job details, listing states, and finding cities. There is no overlap in purpose, so an agent can easily select the right tool.
All tool names follow a consistent verb_noun pattern: find_cities, get_job, list_states, search_jobs. This makes the API predictable and easy to work with.
With only 4 tools, the server is tightly scoped for its purpose of job searching and lookup. Each tool earns its place without unnecessary bulk, making it easy for agents to navigate.
The core workflow of searching and retrieving jobs is fully covered, supplemented by geographic lookup helpers. A minor gap is the lack of a 'recent jobs' or 'browse all' endpoint, but search functionality mitigates this.