Flood, wildfire, soils, terrain, power grid, utilities and parcels for any US location, sourced.
Scored across 15 tools
Every tool has an explicitly delineated role, and the descriptions preempt confusion by naming siblings (fetch_location vs fetch_batch vs start_run; ask vs plan_question; search_fields vs describe_fields vs list_presets; parcel_search vs parcel_enrich vs parcel_coverage). The sync/async, plan/execute, and single/many distinctions are spelled out, so an agent can select correctly even for near-neighbors.
Names are uniformly snake_case and mostly follow verb_noun (fetch_location, get_run, search_fields, start_run) with a clear resource_action family for parcels (parcel_search, parcel_enrich, parcel_coverage). The only deviations are the bare verb 'ask' and the bare noun 'proximity', which slightly break the pattern but remain unambiguous.
Fifteen tools for a rich domain (catalog discovery, point/batch facts, proximity, parcel search/enrich/coverage, geocoding, async runs, usage) is well-scoped. Each tool covers a distinct slice — none reads as filler, and nothing essential is split into redundant variants.
The surface covers the full lifecycle: discovery (search/describe/presets), sync and async execution, paging via get_run, and quota visibility via get_usage. The main gap is run lifecycle management — cancellation is only exposed through the REST API (DELETE /v1/runs/{id}) with no corresponding tool, so agents cannot stop a running job through the server.
Answer a plain-English question about a US place or area in one step: plans it exactly as plan_question does, then runs the plan (point facts, nearest features, a parcel lookup, a parcel search or a geocode) and charges for that call. plan_question is the free, plan-only counterpart (0 lookups, nothing runs) that shows the tool, arguments and estimated cost first; the specific tools give finer control over fields and paging. Output: answer (a short deterministic summary), plan and the full result of the call made. When the plan needs a location or state that was not given, nothing runs and needs lists what is missing. Cost: metered exactly like the tool it calls (a geocode plan is free; a point-facts plan is 1 lookup per 50 fields); max_lookups refuses plans estimated above it, without charge. Behavior: read-only like plan_question, with the access, rate limits, timeouts and latency of the tool it calls; needs an API key or OAuth sign-in. Each ask makes one call, so a parcel search plan returns only its first page (25 parcels by default); parcel_search pages the rest. Errors: question_incomplete (see needs), over_budget (estimate above max_lookups), and any error of the tool it calls.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | WGS84 latitude in decimal degrees (e.g. 30.2672), paired with lng. Optional: the place, when the question does not name it; lat+lng or address, not both. | |
| lng | No | WGS84 longitude in decimal degrees (e.g. -97.7431, negative in the US), paired with lat. | |
| address | No | US street address with city and state (e.g. '350 5th Ave, New York, NY'), geocoded by the US Census geocoder along the street. An alternative to lat+lng; giving both is an invalid_locator error. | |
| question | Yes | The question, 3 to 500 characters (e.g. 'nearest substation to 30.27, -97.74'). | |
| max_lookups | No | Optional budget: plans estimated above this many lookups are refused without charge. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only/open-world/idempotent, but the description goes well beyond: metered cost per call type (geocode free, point-facts 1 lookup per 50 fields), max_lookups refusal without charge, API key or OAuth requirement, inherited rate limits/timeouts/latency, one-call-only semantics limiting parcel search to page one, and named error codes (question_incomplete, over_budget). It also discloses the partial-success path where nothing runs and 'needs' lists missing inputs.
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?
Front-loads the core action and the plan_question contrast before cost and error details, and every clause is substantive. It is dense and long for a single paragraph, with some chaining and parentheticals that could be compressed, but no sentence is filler.
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 metered, agent-orchestrating tool with no output schema, it covers everything an agent needs: what gets returned (answer, plan, full call result), cost model, budget behavior, auth, inherited limits, single-call page limitation, and error taxonomy. Nothing material is left to inference.
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%, so lat/lng/address/question/max_lookups are already documented, including the lat+lng-vs-address exclusion and the invalid_locator error. The description mostly restates the max_lookups refusal rule already in the schema and gestures at the optional-locator case via 'needs', adding little new parameter meaning. 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?
States a specific verb and resource (answer a plain-English question about a US place/area in one step) and immediately pins down the mechanics: it plans like plan_question, then runs one of a named set of call types. It also names the siblings it is not (plan_question, the specific tools, parcel_search), so an agent can route without opening any schema.
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?
Explicitly frames plan_question as the free, plan-only alternative (0 lookups, nothing runs) and says the specific tools give finer control over fields and paging. It also names parcel_search as the paging escape hatch when the first 25-parcel page is insufficient. When-to-use and when-not are both spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the full catalog entry for each named field: description, type, unit, source, source URL, license, attribution, refresh interval and the presets it belongs to. Division of the catalog tools: describe_fields does no searching and takes exact names only, for checking units, provenance or licensing; search_fields finds or lists names by keyword; list_presets lists bundles. Matching: exact and case-sensitive. Output: fields (entries in request order) and unknown (names not in the catalog); unknown names are reported, not an error. Cost: Free. Errors: invalid params when names is empty.
| Name | Required | Description | Default |
|---|---|---|---|
| names | Yes | 1 to 100 exact field names (e.g. ['nfhl_flood_zone', 'slope_degrees']). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that: exact/case-sensitive matching, unknown names are reported rather than erroring, free cost, and the empty-names error. It does not describe pagination or ordering beyond request order, but with annotations carrying the behavior basics a 3 reflects solid but not exhaustive disclosure.
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?
Front-loads the return contents, then the tool-selection rule, then matching, output, cost, and errors in a dense but scannable sequence. Every clause carries operational information; no filler.
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?
There is no output schema, but the description fills that gap by naming the two return keys (fields, unknown) and explaining that unknown names are not errors. Combined with the explicit error case and free cost, an agent has everything needed to call this correctly.
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 coverage is 100% and the single parameter already documents the 1–100 item limit and an example. The description adds meaning the schema does not: matching is exact and case-sensitive, and names must be catalog names rather than search keywords. That is genuine value beyond the schema, though it does not elaborate on array ordering semantics beyond output order.
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?
States a specific verb and resource (return the full catalog entry per named field) and enumerates exactly what the entry contains: description, type, unit, source, license, attribution, refresh interval, presets. It explicitly separates itself from search_fields and list_presets, so an agent can choose it without opening sibling schemas.
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?
Provides an explicit division of labor: describe_fields is for checking units/provenance/licensing with exact names, search_fields for finding names by keyword, list_presets for bundles. It also states the matching mode (exact, case-sensitive) and the error condition, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the same preset and/or fields for several US locations in one synchronous call: the results come back in this response. Size: up to the plan's batch size (10 on Free, 100 on paid plans); fetch_location is the single-place form. More places than the batch size (up to 2000), or work that should not hold the call open, fit start_run with kind=batch, which is asynchronous: it returns a run id at once and get_run pages the results, at the same cost per location. Output: results index-aligned with locations, each with its own ok flag and either fields or an error, plus lookups_charged. One bad location does not fail the others. Cost: 1 lookup per location per started block of 50 delivered fields; locations with no data are free. Places not requested before are fetched live and can take a few seconds each. Behavior: read-only (no side effects); needs an API key or OAuth; each call counts toward the per-minute request limit (Free 10, Starter 60, Pro 300); one call is one request. Places run max_concurrent_locations at a time (Free 1, Starter 4, Pro 8), each waiting up to max_wait_s for slow sources; a place that waits over 20 s for a slot returns error busy (retryable). Lookups count toward the daily cap (Free 200, Starter 5000, Pro 25000). A repeat with the same idempotency_key within 24 h is free. Errors: whole-call errors as fetch_location (preset_unknown, fields_unknown, fields_too_many, no_fields_requested) and batch_too_large above the plan's batch size. Plan limits return rate_limited (with retry_after_s), daily_cap_reached or quota_exhausted.
| Name | Required | Description | Default |
|---|---|---|---|
| detail | No | compact (default): value, unit, status, source and confidence per field. full: the complete record per field, adding license, attribution, vintage and notes. Same cost. | compact |
| fields | No | Exact, case-sensitive field names from list_presets or search_fields (e.g. ['nfhl_flood_zone', 'elevation']). Combined with preset when both are given; up to 50 names that are not already in the preset. Unknown names fail the whole call with fields_unknown. | |
| preset | No | Exact preset name from list_presets (e.g. 'flood_risk', 'terrain', 'solar_siting'). Its fields are added to fields; large presets cost more than 1 lookup (1 per 50 delivered fields). | |
| locations | Yes | 1 to 100 places (capped by the plan's batch size), each an object with lat+lng or address, exactly one of the two. | |
| max_wait_s | No | Seconds to wait for slow live sources before returning those fields as failed; default 10 s, capped at 15 s on Free and 30 s on paid plans. Optional. | |
| idempotency_key | No | Optional 8-128 characters of letters, digits, _ or -. A retry with the same key and arguments within 24 h returns the stored result at no charge. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only/idempotent/open-world, yet the description goes well beyond them: lookup-based cost model (1 per location per started block of 50 delivered fields, no-data locations free), per-plan request/concurrency/daily limits, live-fetch latency, the retryable 'busy' timeout path after 20 s, and free 24 h idempotent replay. This is the kind of operational context annotations cannot carry.
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?
Front-loading is good — purpose and size first, alternatives second, then output, cost, behavior, errors. But the whole definition is one dense paragraph that fuses cost, concurrency, timeout, quota and error taxonomy into a single unbroken block, which hurts scanability and makes some plan-limit detail feel like bulk rather than essentials.
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?
There is no output schema, and the description compensates by describing the return shape: results index-aligned with locations, per-item ok flag with either fields or an error, plus lookups_charged, and the partial-failure guarantee. It also enumerates whole-call error codes and distinguishes them from batch_too_large and plan-limit errors, leaving nothing an agent needs before calling.
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 coverage is 100%, so the baseline is 3; the description still adds value by tying size to plan-dependent batch limits (10 Free / 100 paid) that the schema's static maxItems=100 cannot express, and by noting large presets cost more than 1 lookup. It does not add much on max_wait_s or idempotency_key beyond the already-detailed schema text.
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?
States a specific verb and resource ('Get the same preset and/or fields for several US locations in one synchronous call') and immediately scopes it as the multi-place form of fetch_location. The synchronous-vs-asynchronous split against start_run makes the distinction from siblings unambiguous.
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?
Explicitly routes three cases: this tool for up to the plan's batch size synchronously, fetch_location for a single place, and start_run with kind=batch for >batch size (up to 2000) or work that should not hold the call open. It even states the cost is the same, removing the last reason to guess.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get public-data facts (terrain, flood, wildfire, weather, soils, power grid, utilities, demographics and more) for one US location. The place is lat+lng or a street address; the facts are a preset, a list of field names, or both combined. Sibling tools: fetch_batch takes the same fields for many places in one call, proximity returns nearest features with distances, parcel_enrich returns the property record, and search_fields or list_presets find field names. Output: fields keyed by name, each with value, unit, status (ok; absent = no data at this point; failed = temporary source error), source and confidence, plus the resolved location and attributions. Cost: 1 lookup per started block of 50 delivered fields (a 135-field preset is 3); nothing when no field returns data. Behavior: read-only (no side effects); needs an API key or OAuth; each call counts toward the per-minute request limit (Free 10, Starter 60, Pro 300). Values cached within each field's refresh interval return at once; other places query live sources, waiting up to max_wait_s, and calls over 2 s count toward the slow-lookup limit (Free 5, Starter 20, Pro 60 per minute). Errors: invalid_locator (both or neither of lat+lng and address), coord_out_of_bounds (outside the US), no_fields_requested, preset_unknown (lists known presets), fields_unknown (lists the bad names), fields_too_many. Plan limits return rate_limited (with retry_after_s), daily_cap_reached or quota_exhausted.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | WGS84 latitude in decimal degrees (e.g. 30.2672), paired with lng. Give lat+lng or address, exactly one of the two. | |
| lng | No | WGS84 longitude in decimal degrees (e.g. -97.7431, negative in the US), paired with lat. | |
| detail | No | compact (default): value, unit, status, source and confidence per field. full: the complete record per field, adding license, attribution, vintage and notes. Same cost. | compact |
| fields | No | Exact, case-sensitive field names from list_presets or search_fields (e.g. ['nfhl_flood_zone', 'elevation']). Combined with preset when both are given; up to 50 names that are not already in the preset. Unknown names fail the whole call with fields_unknown. | |
| preset | No | Exact preset name from list_presets (e.g. 'flood_risk', 'terrain', 'solar_siting'). Its fields are added to fields; large presets cost more than 1 lookup (1 per 50 delivered fields). | |
| address | No | US street address with city and state (e.g. '350 5th Ave, New York, NY'), geocoded by the US Census geocoder along the street. An alternative to lat+lng; giving both is an invalid_locator error. | |
| max_wait_s | No | Seconds to wait for slow live sources before returning those fields as failed; default 10 s, capped at 15 s on Free and 30 s on paid plans. Optional. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, but the description goes far beyond them: cost model (1 lookup per 50 delivered fields, free when no data), auth requirement (API key or OAuth), rate limits by plan tier, slow-lookup limits, caching behavior, max_wait_s semantics, and a full error taxonomy including retry_after_s. This is unusually rich behavioral disclosure for a read-only tool.
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?
Purpose is front-loaded, then siblings, output shape, cost, behavior, and errors in a logical order. Despite being dense, every sentence carries actionable information (cost rules, limit tiers, error names) with no filler or repetition of the title.
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 7-parameter, open-world enrichment tool with no output schema, the description supplies the return shape (field name → value, unit, status, source, confidence, plus resolved location and attributions), cost and quota behavior, and error handling. An agent has everything needed to call it correctly and interpret partial failures.
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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it frames the locator as an either/or choice ('lat+lng or a street address'), explains that preset and fields can be combined, and links preset size to cost ('1 per 50 delivered fields'). It stops short of explaining detail=compact vs full, which the schema already covers.
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?
States a specific verb and resource ('Get public-data facts ... for one US location') and enumerates the data domains covered. It explicitly names each sibling tool and what it does instead, so an agent can distinguish fetch_location from fetch_batch, proximity, parcel_enrich, search_fields, and list_presets without opening their schemas.
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?
Explicitly routes the agent: fetch_batch for many places, proximity for nearest features, parcel_enrich for the property record, search_fields/list_presets to discover names. It also states the locator rule (lat+lng or address, not both) and the error conditions that select failure modes, leaving little to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turn a US street address into lat/lng plus the normalized address, using the US Census geocoder. The returned lat/lng can be passed to fetch_location, fetch_batch, proximity or parcel_enrich, which also accept the address directly and geocode it the same way. Output: lat, lng, normalized_address, accuracy (1 for a single match, lower when several candidates matched), accuracy_type and precision_note. Points are placed along the street from the house-number range, not on the rooftop, so they can be off on large rural lots. Cost: Free (0 lookups), up to 10,000 geocodes per key per day. Behavior: read-only (no side effects); needs an API key or OAuth; each call counts toward the per-minute request limit (Free 10, Starter 60, Pro 300). Works with an empty balance; each call queries the Census geocoder live with a 30 s timeout, and the 10,000 per day cap resets at 00:00 UTC. Errors: address_not_found when nothing matches, daily_cap_reached (resets 00:00 UTC), upstream_unavailable (retryable).
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | US street address with house number, street, city and state (e.g. '350 5th Ave, New York, NY 10118'). PO boxes and a bare city or ZIP do not geocode. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description provides extensive context beyond the standard annotations, including operational details like cost, rate limits (daily/per minute), time limits (30s timeout), required authentication (API key), specific behavioral quirks (points placed along the street), and detailed error handling.
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?
Despite its length, the definition is perfectly structured. Every complex detail—usage, cost, behavior, errors—is front-loaded and highly efficient, earning its place through its high information density.
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?
It is complete. It defines the expected output fields (`lat`, `lng`, `normalized_address`, `accuracy`, etc.) and covers all operational aspects (limits, errors, behavior) that an agent would need to decide whether to call the tool successfully.
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?
While schema coverage is 100%, the description adds critical semantic constraints, explicitly defining required format components (number, street, city, state, ZIP) and stating what is invalid (PO boxes, bare ZIP).
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 immediately identifies the specific action (Turn address into lat/lng) and resource (US street address) and clearly distinguishes its scope and purpose from related fetching and batch tools.
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?
It provides direct routing advice, stating that the resulting lat/lng can be passed to several downstream tools (`fetch_location`, `proximity`, etc.), but also clarifies that these tools can handle the address directly as an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the status, progress and lookups charged for a run started with start_run, plus a page of its results (available while it is still running); with no run_id, list the account's recent runs. Output: id, kind, status (queued, running, succeeded, stopped at max_lookups or a quota, failed or cancelled), error, progress {total, done, ok, failed, pages}, lookups_charged, lookups_held, expires_at (7 days after the run ends), results, results_offset and next_offset (null on the last page). Pages are read by passing next_offset as offset. Cost: Free. Errors: run_not_found (unknown, another account's, or expired). A run is cancelled with DELETE /v1/runs/{id} on the REST API.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Results to include, 0 to 500 (default 50); 0 returns status only. | |
| offset | No | Index of the first result to include (default 0); next_offset from the previous call gives the next page. | |
| run_id | No | Run id from start_run (run_ followed by 24 hex characters). Omit to list recent runs. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent, and the description adds substantial context beyond them: full status enumeration, expiry semantics (7 days after the run ends), cost (Free), and a specific error case (run_not_found for unknown, foreign, or expired runs). This is unusually rich behavioral disclosure.
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?
It is a dense single block, but front-loaded with the core action and mode split before output details, cost, and errors. Every sentence carries information; minor cost is that the output-field enumeration is a long run-on list that could be structured, but no sentence is wasted.
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?
With no output schema, the description carries the full return-value burden and does so thoroughly (id, kind, status, error, progress, lookups, expires_at, results, next_offset). Combined with 100% parameter coverage, an agent has everything needed to call and interpret it.
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 coverage is 100%, so baseline is 3; the description adds meaning by linking the offset parameter to the next_offset output field and explaining pagination behavior, and clarifies the run_id format ('run_ followed by 24 hex characters') and omit-to-list behavior.
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 opens with a specific verb and resource ('Get the status, progress and lookups charged for a run') and immediately distinguishes two modes: with run_id it fetches one run's status/results, without it lists recent runs. It explicitly ties itself to the sibling start_run, so an agent can route between them.
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?
It explains when results are available ('while it is still running'), how to page (pass next_offset as offset), and points to the REST DELETE endpoint for cancellation rather than implying this tool cancels. It lacks explicit when-not-to-use guidance relative to other siblings like get_usage, but provides clear operational context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the caller's plan, its limits and the lookups left, for example to see whether a large fetch_batch, parcel_search page or start_run fits the remaining balance. Other tools report lookups_charged per call; this shows the totals. Output: account_id, plan, limits (lookups_per_period, rpm, max_batch, max_concurrent_locations, slow_lookups_per_min, daily_lookup_cap, max_wait_s_cap), balance (remaining, allowance_remaining, topup_remaining and period_end), used_today and daily usage for the last 30 days. Cost: Free. Takes no arguments.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive, and closed-world behavior, but the description adds meaningful context beyond them: the call is free, takes no arguments, and returns a specific set of plan, balance, and usage fields. It also clarifies the relationship to per-call lookups_charged reporting in other tools.
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 front-loaded with purpose and usage context, then provides output details because no output schema exists. Every sentence contributes: the sibling comparison, the example use cases, the output field list, the cost note, and the no-argument confirmation all help the agent invoke the tool correctly.
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?
There is no output schema, so the description carries the burden of explaining return values, and it does so in detail: account_id, plan, limits, balance, used_today, and 30-day usage. Combined with the annotations covering safety and the explicit no-argument statement, the description is complete for this tool.
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 tool has zero parameters and the schema coverage is 100%. The description confirms 'Takes no arguments,' which aligns with the schema and removes ambiguity. With no parameters to explain, this hits the baseline for a zero-argument tool.
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 a specific verb and resource: 'Get the caller's plan, its limits and the lookups left.' It also distinguishes this tool from siblings by noting 'Other tools report lookups_charged per call; this shows the totals,' so an agent can tell it apart from fetch_batch, parcel_search, and start_run without opening the schema.
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?
It gives concrete usage context, naming sibling tools: check whether 'a large fetch_batch, parcel_search page or start_run fits the remaining balance.' That is clearer than most definitions, though it does not explicitly state when not to use this tool or list exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the named field bundles (presets), such as terrain, flood_risk, natural_hazard, utilities, solar_siting and data_center_siting, with every field name in each. A preset name can be passed as preset to fetch_location, fetch_batch, parcel_enrich or start_run. Division of the catalog tools: list_presets answers which bundles exist and what is in them (names only); search_fields finds individual fields by keyword, or lists the catalog with an empty query; describe_fields returns full metadata (source, license, units) for exact names. Output: presets [{name, count, fields}] and fields_per_lookup (50); with preset, just {preset, count, fields}. Cost: Free. Errors: preset_unknown, with the list of known presets.
| Name | Required | Description | Default |
|---|---|---|---|
| preset | No | Optional exact preset name (e.g. 'flood_risk') to return only its fields. Omit to list every preset. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only/idempotent/destructive=false, and the description goes well beyond: it documents the exact return shape (presets [{name, count, fields}] plus fields_per_lookup (50)), the reduced shape when preset is supplied, that the call is free, and the specific error code preset_unknown with known presets returned. That is real operational context an agent cannot get from the annotations.
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?
Front-loads the purpose, then routes to alternatives, then output, cost and errors in a compact labeled sequence. Dense but zero filler; every sentence (including the sibling-tool division and the output-shape note) carries distinct information.
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?
There is no output schema, yet the description fully specifies the return payload, the single-parameter variant, the absence of cost, and the failure mode. For a one-parameter read-only catalog tool, nothing an agent needs 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 coverage is 100%, so the baseline is 3, but the description adds relational semantics: the value must be an exact preset name drawn from this catalog, and it is the same value accepted as 'preset' by four sibling tools. It does not restate format/case rules beyond 'exact', which keeps it just short of 5.
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?
States a specific verb+resource ('List the named field bundles (presets)') and immediately grounds it with concrete preset examples (terrain, flood_risk, natural_hazard...). The division-of-catalog-tools paragraph makes it unmistakable against siblings like search_fields and describe_fields.
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?
Explicitly partitions the three catalog tools: list_presets answers 'which bundles exist and what is in them (names only)', search_fields finds by keyword or lists with an empty query, describe_fields returns full metadata for exact names. It also tells the agent where the returned preset names are consumed (fetch_location, fetch_batch, parcel_enrich, start_run).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the states with parcel data, or one state in detail, to see whether parcel_search and parcel_enrich can answer there and which columns (owner, values, sale, zoning...) are published. Output without state: total_parcels and, per state, parcel and county counts, publisher, licence, data vintage, refresh cadence, owner-privacy policy and required attribution. With state: the same plus field_fill, the share of parcels with each column filled; an uncovered state returns covered: false. Cost: Free. Behavior: read-only (no side effects); needs an API key or OAuth; each call counts toward the per-minute request limit (Free 10, Starter 60, Pro 300). The whole list comes back in one response (no paging), served from a cache refreshed every 10 minutes. Owner names and mailing addresses are withheld in CA, OR and VT, and mailing addresses in MT. Errors: parcels_unavailable (temporary, retryable).
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | Optional two-letter state code, case-insensitive (e.g. 'TX'). Given: that state with per-column fill rates. Omitted: every covered state without fill rates. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only/idempotent/no-side-effects, yet the description adds substantial non-structured context: cost (Free), auth requirement (API key or OAuth), per-minute rate limits by tier (10/60/300), no pagination, a 10-minute cache refresh, jurisdiction-specific privacy withholding (CA, OR, VT, MT), and a named retryable error (parcels_unavailable). These are exactly the operational facts an agent needs before calling and retrying, and none contradict the readOnlyHint=true annotation.
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 long but front-loaded: purpose and routing come first, then output shape, then cost/behavior/limits, then errors. Some sentences are dense enumerations ('total_parcels and, per state, parcel and county counts, publisher, licence, data vintage, refresh cadence...'), but each carries information an agent would otherwise have to guess at, since there is no output schema.
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?
There is no output schema, so the description carries the full burden of describing return values — and it does, for both the list mode and the single-state mode, plus the negative case and the error contract. Auth, rate limits, caching and privacy caveats round out a complete picture for a one-parameter read tool.
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 single optional 'state' parameter is fully documented there, including case-insensitivity and the given-vs-omitted semantics. The description largely restates that contract rather than adding new meaning; its only marginal addition is the covered:false outcome for uncovered states, which is really return-value behavior.
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 opens with a specific verb and resource ('List the states with parcel data, or one state in detail') and immediately frames its role relative to siblings parcel_search and parcel_enrich. An agent can tell this is a coverage/capability-check tool, not a data-retrieval tool, without inspecting the schema.
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?
It gives an explicit decision rule: use it 'to see whether parcel_search and parcel_enrich can answer there', and names the two modes (omit state vs. supply state) with their respective outcomes. It also names the uncovered-state case ('an uncovered state returns covered: false'), so the agent knows how to interpret a negative result rather than assuming an error.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the public parcel (property) record for one US parcel, located by exactly one of: lat+lng, street address (matched to the parcel's situs address nearby), parcel_id from an earlier result, or apn+state. Sibling tools: parcel_search finds many parcels by criteria and returns lighter records; start_run (kind=enrich) enriches up to 1000 parcels; parcel_coverage lists covered states and their columns. Output: parcel with owner of record and mailing address (null with privacy.reason where the source or state law withholds them), situs address, land use, zoning where published, assessed/land/improvement values, last sale, year built, legal description, acres, square feet, perimeter, centroid, bounding box and shape metrics; the GeoJSON boundary with include_geometry; point_fields computed at the centroid when fields or preset are given. Columns vary by state. Cost: 5 lookups per matched parcel plus 1 per started block of 50 point fields that return data; nothing when no parcel matches. Errors: invalid_locator (none or several locators), parcel_not_found (free; also outside covered states), fields_unknown, preset_unknown. Plan limits return rate_limited (with retry_after_s), daily_cap_reached or quota_exhausted.
| Name | Required | Description | Default |
|---|---|---|---|
| apn | No | The publisher's parcel number (APN/PIN); spaces and punctuation are ignored. Requires state. | |
| lat | No | WGS84 latitude in decimal degrees (e.g. 30.2672), paired with lng. One of four locators: lat+lng, address, parcel_id or apn+state. | |
| lng | No | WGS84 longitude in decimal degrees (e.g. -97.7431, negative in the US), paired with lat. | |
| state | No | Two-letter state code (e.g. 'TX'), required with apn and unused otherwise. | |
| county | No | Optional county, 5-digit FIPS or name, to disambiguate an apn that repeats across counties. | |
| fields | No | Optional point-field names (from search_fields) computed at the parcel centroid and returned in point_fields. Parcel columns are always returned and need not be listed. | |
| preset | No | Optional preset of point fields (from list_presets) computed at the parcel centroid, combined with fields. | |
| address | No | US street address with city and state (e.g. '350 5th Ave, New York, NY'), geocoded by the US Census geocoder along the street. An alternative to lat+lng; giving both is an invalid_locator error. | |
| parcel_id | No | Isopleth parcel id from an earlier parcel_search or parcel_enrich result (e.g. 'tx-1234567'). Ids change when a state's data is refreshed. | |
| max_wait_s | No | Seconds to wait for slow live sources before returning those fields as failed; default 10 s, capped at 15 s on Free and 30 s on paid plans. Optional. | |
| include_geometry | No | true adds the parcel boundary as GeoJSON (can be large). Default false; acreage and shape metrics are returned either way. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive, open-world behavior. The description adds substantial context beyond annotations: cost per matched parcel and per point-field block, free no-match behavior, privacy withholding of owner/mailing fields, state-dependent columns, and plan-related errors including rate_limited with retry_after_s.
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 dense and long, but it is front-loaded with purpose and locator rules before moving to sibling differentiation, outputs, cost, and errors. Most sentences carry operational value for a complex lookup tool, though the output and error inventory could be tightened.
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?
There is no output schema, so the description carries the return-value burden and does so thoroughly: owner/mailing address privacy behavior, situs address, land use, zoning, values, sale, built year, legal description, geometry, and point_fields. It also documents state variation and error conditions, making the definition complete for safe and correct invocation.
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 coverage is 100%, so parameter definitions are already strong. The description still adds useful semantic constraints not fully captured in individual schema fields, especially the exactly-one-locator rule, the free no-match behavior, point-field cost, and centroid computation for fields/preset.
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 a specific verb and resource: get the public parcel record for one US parcel. It clearly defines the accepted locator forms and distinguishes parcel_enrich from parcel_search, start_run(kind=enrich), and parcel_coverage, so an agent can identify the correct tool without opening other schemas.
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 the parcel must be located by exactly one of lat+lng, street address, parcel_id, or apn+state, and names sibling alternatives with their distinct roles. It also covers error cases such as invalid_locator when multiple locators are supplied, which directly guides correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find parcels matching criteria within one or more covered states: county, acreage, owner name, land use, total or land value, sale price or date, year built, ZIP, city, a bbox or GeoJSON polygon, or generic column filters. All criteria are ANDed; state (or bbox/polygon) is required. Sibling tools: parcel_enrich returns the full record for one parcel (pass its parcel_id) with optional point fields; start_run (kind=search) walks many pages asynchronously; parcel_coverage lists states and which columns each publishes. Output: results, one per parcel with parcel_id and its columns (detail=summary: key columns; detail=full: every published column plus shape metrics), has_more and next_cursor for the next page. Owner and mailing-address criteria are refused where a state withholds those fields, and parcels with a withheld owner are left out of owner-matched results. Cost: 25 lookups per page that returns parcels, whatever its size (up to 100); an empty page is free. Behavior: read-only (no side effects); needs an API key or OAuth; each call counts toward the per-minute request limit (Free 10, Starter 60, Pro 300). Searches run 1 at a time per key on Free, 2 on paid plans; waiting over 20 s for a slot gives busy (503) and running over 40 s gives upstream_timeout (504), both retryable and free. The page cost must be available upfront. Errors: state_required, owner_search_unavailable and mailing_search_unavailable (fields withheld in that state), invalid_request for malformed filters. Plan limits return rate_limited (with retry_after_s), daily_cap_reached or quota_exhausted.
| Name | Required | Description | Default |
|---|---|---|---|
| zip | No | Situs ZIP code, 5 digits. | |
| bbox | No | Bounding box [min_lng, min_lat, max_lng, max_lat] in WGS84. | |
| city | No | Situs city name, case-insensitive. | |
| limit | No | Parcels per page, 1 to 100 (default 25). A page costs the same at any size. | |
| owner | No | Owner name to match, case-insensitive (e.g. 'SMITH JOHN' or 'ACME LLC'), matched per owner_match. | |
| state | No | Two-letter state code or a list (e.g. 'TX' or ['TX', 'OK']). Required unless bbox or polygon is given. | |
| county | No | County 5- or 3-digit FIPS or name, or a list; one state only. | |
| cursor | No | next_cursor from the previous page, with the same criteria, for the next page. | |
| detail | No | summary (default): key columns. full: every published column plus shape metrics. Same cost. | summary |
| filters | No | Up to 20 generic column filters, ANDed with the other criteria. Columns are listed by parcel_coverage. | |
| polygon | No | GeoJSON Polygon or MultiPolygon; parcels whose interior point falls inside match. | |
| usecode | No | Publisher land-use code or list of codes, exact (codes differ by state). | |
| land_use | No | Words in the land-use description, or a code (e.g. 'agricultural', 'vacant'). | |
| acres_max | No | Maximum parcel area in acres (inclusive). | |
| acres_min | No | Minimum parcel area in acres (inclusive). | |
| value_max | No | Maximum total value in USD. | |
| value_min | No | Minimum total value in USD as published (assessed or market; see parvaltype in full records). | |
| owner_match | No | prefix (default, fast): owner name starts with owner. contains: owner appears anywhere in the name (slower). | prefix |
| sale_date_max | No | Latest last-sale date, YYYY-MM-DD (inclusive). | |
| sale_date_min | No | Earliest last-sale date, YYYY-MM-DD (inclusive). | |
| land_value_max | No | Maximum land value in USD. | |
| land_value_min | No | Minimum land value in USD. | |
| sale_price_max | No | Maximum last sale price in USD. | |
| sale_price_min | No | Minimum last sale price in USD. | |
| year_built_max | No | Latest year built. | |
| year_built_min | No | Earliest year built (e.g. 1990). | |
| include_geometry | No | true adds each parcel's GeoJSON boundary (large). Default false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, open-world, and non-destructive behavior, but the description adds substantial operational context beyond them: cost of 25 lookups per non-empty page, free empty pages, API-key/OAuth requirement, per-plan request limits, concurrency limits, retryable busy/upstream_timeout errors, and withheld-owner filtering behavior. There is no contradiction with the annotations.
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 long and dense, but the tool has 27 parameters and many operational constraints, so most of the content earns its place. It is front-loaded with purpose and required geography, though the single-paragraph structure with heavy semicolon use could be easier to scan.
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?
With no output schema, the description still explains the return shape: results with parcel_id and columns, detail=summary versus full, has_more, and next_cursor. It also covers cost, plan limits, concurrency, timeouts, and error cases, leaving little an agent needs to infer before calling it correctly.
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%, with detailed per-parameter descriptions for ZIP, bbox, county, filters, detail, owner_match, and every range parameter. The description adds the useful AND semantics and required geography rule, but it does not add much per-parameter meaning beyond what the schema already provides, so the high-coverage baseline of 3 is appropriate.
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 opens with a specific verb and resource: 'Find parcels matching criteria within one or more covered states.' It lists the searchable criteria and explicitly names sibling tools, so an agent can distinguish parcel_search from parcel_enrich, start_run, and parcel_coverage without opening other schemas.
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?
It states the core requirement that state, bbox, or polygon is required, and it explicitly routes to alternatives: parcel_enrich for a full single-parcel record, start_run for asynchronous multi-page walks, and parcel_coverage for available states and columns. It also notes when owner or mailing-address criteria are unavailable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Map a plain-English question about a US place or area to the tool that answers it, that tool's exact arguments (fields, preset, filters, feature types) and the estimated lookup cost. Plan only: nothing runs and nothing is charged (0 lookups). ask is the same planner plus execution, charged like the tool it calls; the returned tool name and arguments can also be passed to that tool directly. Planning uses deterministic rules and the field catalog, no language model. Output: plan with tool, arguments, estimated_lookups, explanation, matched (the topics and keywords that set the arguments), needs (what is missing, such as location or state), ready (true when needs is empty) and confidence (high, medium or low). A question with no recognised topic falls back to the general site_selection preset with needs_clarification and low confidence. Cost: Free (0 lookups).
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | WGS84 latitude in decimal degrees (e.g. 30.2672), paired with lng. Optional: the place, when the question does not name it; lat+lng or address, not both. | |
| lng | No | WGS84 longitude in decimal degrees (e.g. -97.7431, negative in the US), paired with lat. | |
| address | No | US street address with city and state (e.g. '350 5th Ave, New York, NY'), geocoded by the US Census geocoder along the street. An alternative to lat+lng; giving both is an invalid_locator error. | |
| question | Yes | The question, 3 to 500 characters (e.g. 'flood zone and elevation at 1600 Pennsylvania Ave, Washington DC' or 'parcels over 40 acres in Travis County TX'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: no execution, zero lookups charged, deterministic rule-based planning with no language model, and the fallback to site_selection with needs_clarification and low confidence. That last piece is behavior an agent could not infer from annotations and materially affects how it should interpret results.
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?
Purpose and the plan-vs-execute distinction are front-loaded, and most sentences carry weight. The middle output-field enumeration reads as a dense run-on and could be tightened, but it is doing real work given there is no output schema.
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?
With no output schema, the description compensates by enumerating the return shape (tool, arguments, estimated_lookups, explanation, matched, needs, ready, confidence) and the degradation behavior. Cost, determinism, and prerequisites are all covered, so an agent has everything needed to call and interpret it.
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 coverage is 100% and the schema itself already explains lat/lng pairing, the address alternative, and the mutual-exclusion error. The description adds nothing about any of the four input parameters, so the baseline of 3 is appropriate.
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?
Uses a specific verb and resource ('Map a plain-English question ... to the tool that answers it') and immediately scopes it as planning-only rather than execution. It explicitly distinguishes itself from the sibling `ask` ('the same planner plus execution'), so an agent can pick between them without reading either schema.
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?
States the when ('Plan only: nothing runs and nothing is charged') and names the alternative with its trade-off ('ask is the same planner plus execution, charged like the tool it calls'). It also gives the fallback path for questions with no recognised topic, leaving no ambiguity about selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the nearest mapped feature of each requested type to one US point or address, from about 50 types in 7 categories: power (substation, transmission_line, power_plant, solar_facility), pipelines, transportation (major_road, rail_line, airport), places (hospital, school, fire_station), water (wetland, dam, coast), environment (superfund, brownfield) and telecom. fetch_location returns non-distance facts at the point; ask may call this tool. Selection: features and categories combine (synonyms such as 'power line' or 'cell tower' work); with neither, 14 default types are used. Output: features nearest first, each with type, label, category, status, straight-line distance_m/km/mi, source, name, attributes and counts where published, and within_radius when radius_m is given. Distances come from public datasets, not a survey. Cost: 1 lookup per call covering up to 50 underlying fields (radius counts are dropped first if more are needed); nothing when no data returns. Behavior: read-only (no side effects); needs an API key or OAuth; each call counts toward the per-minute request limit (Free 10, Starter 60, Pro 300); a cold point can take up to 120 s, and calls over 2 s count toward the slow-lookup limit (Free 5, Starter 20, Pro 60 per minute). A type whose source fails has status failed with error and retryable; a type with no data is listed in unavailable_types. Errors: invalid_locator, coord_out_of_bounds, proximity_type_unknown (lists unknown names and known categories). Plan limits return rate_limited (with retry_after_s), daily_cap_reached or quota_exhausted.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | WGS84 latitude in decimal degrees (e.g. 30.2672), paired with lng. Give lat+lng or address, exactly one of the two. | |
| lng | No | WGS84 longitude in decimal degrees (e.g. -97.7431, negative in the US), paired with lat. | |
| address | No | US street address with city and state (e.g. '350 5th Ave, New York, NY'), geocoded by the US Census geocoder along the street. An alternative to lat+lng; giving both is an invalid_locator error. | |
| features | No | Feature types (e.g. ['substation', 'transmission_line', 'hospital']); case-insensitive, spaces or hyphens allowed, common synonyms accepted. About 20 types fit in one call. | |
| radius_m | No | Optional radius in meters (up to 500000); each feature is flagged within_radius true or false. Does not limit the search. | |
| categories | No | Whole categories, any of: power, pipelines, water, transportation, places, environment, telecom. Added to features. | |
| max_wait_s | No | Optional; accepted for consistency with fetch_location but not applied here: a proximity call waits up to 120 s for its sources. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, yet the description adds substantial context beyond them: API key/OAuth requirement, per-minute and slow-lookup rate limits by tier, 1-lookup-per-call cost accounting, 120s cold-start latency, partial-failure semantics (status failed with retryable, unavailable_types), and a full error taxonomy. It stops short of describing pagination or ordering guarantees beyond 'nearest first', but the behavioral disclosure is well above the annotation baseline.
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?
Front-loaded with purpose, then organized into Selection/Output/Cost/Behavior/Errors blocks, all of which earn their place for a tool with this much behavior. It is dense and a few clauses (e.g. radius flagging) restate schema text, keeping it from a 5, but there is little true filler.
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?
With no output schema, the description carries the return-shape burden and does so: nearest-first ordering, per-feature fields (type, label, category, status, distance in m/km/mi, source, name, attributes, within_radius), plus partial-failure and error handling. Given 7 params and a rich behavioral surface, nothing an agent needs 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 coverage is 100%, so the baseline is 3, but the description adds real semantics the schema does not: how features and categories combine, that neither yields 14 defaults, and that synonyms are resolved. It also reinforces that radius_m flags rather than filters. These additions justify moving above baseline.
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?
Opens with a specific verb+resource: 'Find the nearest mapped feature of each requested type to one US point or address', and enumerates the 7 categories so an agent knows the scope immediately. It also distinguishes itself from the sibling fetch_location by stating that fetch_location returns non-distance facts at the point.
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?
Explicitly routes between siblings ('fetch_location returns non-distance facts...; ask may call this tool') and gives selection rules for its own inputs: features and categories combine, synonyms are accepted, and 14 default types apply when neither is given. The conditions that select this tool versus alternatives are stated, not implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the field catalog by keywords such as 'flood zone', 'substation', 'wildfire' or 'broadband' to find field names for fetch_location, fetch_batch or parcel_enrich. With an empty query it lists the catalog itself, up to 200 fields per call, narrowed by preset or source to reach the rest. Division of the catalog tools: search_fields discovers names (with type, unit, source and description); describe_fields only looks up exact names already known and adds source URL, license, attribution and refresh interval; list_presets lists bundles. Matching: case-insensitive; every word must appear somewhere in the field name (underscores read as spaces), description or source id; optionally narrowed to one preset or source. Output: total matches, returned count and fields [{name, type, unit, source, description}]; no match gives total 0 and an empty list. Cost: Free. Behavior: read-only (no side effects); needs an API key or OAuth; each call counts toward the per-minute request limit (Free 10, Starter 60, Pro 300). Reads the gateway's field catalog, cached for up to 1 hour, so no live data source is called and results return quickly. Errors: preset_unknown (lists known presets).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum fields to return, 1 to 200 (default 40). total still counts every match. | |
| query | No | Space-separated keywords, all of which must match (substring, case-insensitive). Empty or omitted matches every field. | |
| preset | No | Optional exact preset name; only that preset's fields are searched. | |
| source | No | Optional source id prefix, case-insensitive (e.g. 'FEMA', 'USGS'); only fields from matching sources are searched. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnlyHint/idempotentHint annotations: discloses auth requirements (API key or OAuth), per-minute rate limits by tier, that results come from a catalog cached up to 1 hour with no live source call, the exact error code (preset_unknown), and the return shape with the no-match case. This is unusually rich behavioral context.
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?
Front-loaded with purpose and sibling routing, then matching, output, cost, and errors; nearly every sentence carries information. It is dense and long, but the density is justified rather than padded.
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?
No output schema exists, yet the description specifies the return fields, total vs returned count, and the empty-result case, plus errors and authentication. Nothing an agent needs to invoke this 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 coverage is 100%, so the baseline is 3; the description still adds matching semantics not in the schema, notably that underscores in field names are read as spaces and that matching spans name, description, or source id. It stops short of adding format detail for preset/source beyond what the schema already states.
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?
States a specific verb and resource ('Search the field catalog by keywords') and gives concrete example queries. It also explicitly delineates the division of labor against siblings describe_fields and list_presets, so an agent can route correctly without opening schemas.
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?
Explicitly says when to use this tool ('discovers names') versus describe_fields ('only looks up exact names already known') and list_presets. It also documents the empty-query behavior and the preset/source narrowing path to reach results beyond the 200 cap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit work too large for one call as an asynchronous run in the caller's account: it returns a run id at once and get_run reports progress and pages the results. kind=batch: up to 2000 locations with the same fields, processed in plan-sized batches; fetch_batch is the synchronous form for up to the plan's batch size (10 on Free, 100 on paid plans) with results in the same response. kind=enrich: up to 1000 parcel locators, like parcel_enrich; kind=search: one parcel_search body walked page by page up to max_pages. Output: the run object (id like run_..., status queued, estimated_max_lookups, lookups_held, status_url and results_url). Cost: metered like the underlying calls (batch 1 lookup per location per 50 fields; enrich 5 per matched parcel plus point fields; search 25 per page with results). The worst case, or max_lookups if lower, is held upfront and the unused part is refunded when the run ends; the run stops before spending more than max_lookups. Results are kept 7 days after the run ends. Errors: run_input_missing, invalid_locator, too_many_rows, no_fields_requested, state_required, too_many_active_runs (2 at once), quota_exhausted (with the hold needed).
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | batch (needs locations and fields/preset), enrich (needs items) or search (needs search). | |
| items | No | kind=enrich: up to 1000 parcel locators, each exactly one of {lat, lng}, {address}, {parcel_id} or {apn, state} (optional county). | |
| fields | No | Field names for kind=batch, or point fields at each parcel centroid for kind=enrich; up to 50 besides the preset. | |
| preset | No | Preset name from list_presets for kind=batch or kind=enrich, combined with fields. | |
| search | No | kind=search: a parcel_search argument object (state, or bbox/polygon, required; limit up to 100 per page). | |
| locations | No | kind=batch: up to 2000 places, each with lat+lng or address. | |
| max_pages | No | kind=search: pages to walk, 1 to 40 (default 10); the run stops early when pages run out. | |
| max_lookups | No | Optional spending cap for the whole run; it is also the upfront hold when lower than the estimate. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare the mutation/idempotency profile; the description adds substantial non-obvious behavior: upfront worst-case hold with refund of the unused part, a hard stop at max_lookups, 7-day result retention, a 2-concurrent-run cap, and a named error list including quota_exhausted with the hold needed. Nothing here contradicts readOnlyHint=false / destructiveHint=false.
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?
Front-loaded with the core purpose and per-kind semantics before cost and error detail, and nearly every sentence carries operational information. It is a dense single paragraph with cost/error detail packed into long clauses, which slightly hurts scanability.
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 an 8-parameter async job tool with nested objects and no output schema, the description supplies the return shape (id like run_..., status queued, estimated_max_lookups, lookups_held, status_url, results_url), the cost model per kind, retention, and the failure modes — everything needed to call it and interpret the result.
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 coverage is 100%, so the baseline is 3; the description still adds value by tying parameters together (which params each kind needs, max_lookups doubling as the hold, max_pages walking limit of a parcel_search body). Minor gap: it doesn't restate the fields/preset interaction beyond what the schema already says.
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?
States a specific verb and resource ('Submit work ... as an asynchronous run') plus the immediate effect ('returns a run id at once') and the delegation to get_run for progress/results. It then enumerates the three kind values with distinct semantics, so an agent can tell start_run apart from the synchronous fetch_batch, parcel_enrich and parcel_search siblings.
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?
Explicit routing rules: use this when work is 'too large for one call', otherwise fetch_batch is the synchronous form, with concrete thresholds (2000 locations vs 10/100 batch size; 1000 enrich items; max_pages 1-40). Each kind names the sibling it mirrors, so the when-to-use decision is fully specified rather than inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
askdescribe_fieldsfetch_batchfetch_locationgeocode_addressget_runget_usagelist_presetsparcel_coverageparcel_enrichparcel_searchplan_questionproximitysearch_fieldsstart_runUS site diligence for agents: parcels, power, flood, zoning rules and more, each with its source.
Zoning, ADU eligibility, flood zone, setbacks, and buildability intelligence for U.S. parcels.
US property data: powerlines, noise, crime, hazards, schools and more
Property intelligence: 180M+ US parcels — lookup, search, owners, hazards, permits, deeds.
Add one secure layer between your agents and this server.
