Address validation & geocoding for AI agents: 240+ countries, UK PAF, free US/CA enrichment
Scored across 9 tools
Most tools target a clearly different operation (autocomplete, geocode, reverse geocode, UK postcode expansion, batch validation, balance, trial key). The one real overlap is enrich_us_ca_address versus validate_address, since validate_address already returns the same free census enrichment for street-accurate USA/Canada matches, so an agent could reasonably pick either. Descriptions do explicitly steer callers (e.g. 'use validate_address for UK', 'geocode returns no verdict'), which keeps the confusion contained.
Every name is snake_case, verb-first, and noun-scoped: autocomplete_address, check_balance, enrich_us_ca_address, expand_uk_postcode, geocode_address, reverse_geocode, request_trial_key, validate_address, validate_addresses_batch. The geocode/reverse_geocode and validate/validate_addresses_batch pairs follow a predictable, readable pattern.
Nine tools is well within the ideal range and each corresponds to a distinct capability of a geo/address API (suggest, validate, batch validate, geocode, reverse geocode, enrich, UK PAF expand, account balance, trial key). Nothing looks padded or redundant at the count level.
Core address lifecycle is fully covered: type-ahead, validation (single and batch), forward and reverse geocoding, UK PAF point expansion, plus account and trial-key management. Minor gaps remain: check_balance references email and phone credit pools but no email/phone validation tools are exposed, and there is no batch geocoding or batch reverse-geocoding counterpart to the batch validator.
Address autocomplete (type-ahead): ranked, standardized address suggestions for a
partial input q (typed so far), with lat/lng whenever the reference row
carries a coordinate. Use it to help a person pick an address, then pass
the chosen one to validate_address.
`country` is ISO-3 lowercase. `limit` 1-50 (default 10). `state` narrows
USA/Canada. For UK (gbr) the query may be, or start with, a postcode:
a full or partial postcode returns every delivery point there (labelled
with building/organisation names). UK requests are served from the Royal
Mail PAF service; suggestions do not carry UDPRN/UPRN, so validate the
chosen address to get them.
Cost: billed exactly like the /suggest endpoint it wraps; see
https://www.acuris-geo.com/acuris-pricing/| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | ||
| limit | No | ||
| state | No | ||
| country | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, and it does so well: it states results are ranked and standardized, that lat/lng is present only 'whenever the reference row carries a coordinate', that UK requests come from Royal Mail PAF, that UK suggestions lack UDPRN/UPRN and require a follow-up validate call, and that the call is billed. These are exactly the non-obvious operational facts an agent needs and none are derivable from the schema.
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 core purpose and the validate_address handoff are front-loaded in the first two sentences, followed by compact parameter notes and a one-line cost disclosure. It is dense but each part earns its place; only the trailing pricing URL sentence runs slightly long for what it conveys.
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 and no annotations, the description still tells the agent what comes back (ranked standardized suggestions with optional coordinates, UK delivery points labelled with building/organisation names), what constraints apply per country, and what follow-up call is needed. Nothing required to call or chain it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description has to define all four parameters, and it does: `q` is the partial text typed so far, `country` is ISO-3 and lowercase, `limit` is 1-50 with default 10, and `state` narrows results for USA/Canada. It adds format and range constraints the bare schema lacks.
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 names a specific verb and resource ('Address autocomplete (type-ahead)') plus the returned artifact ('ranked, standardized address suggestions') and the input it operates on ('a partial input `q` typed so far'). That framing is enough to separate it from validate_address, geocode_address, and reverse_geocode 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?
It gives a concrete use case and a next-step handoff: 'Use it to help a person pick an address, then pass the chosen one to validate_address.' It also conditions behavior by country, including the UK postcode case. It stops short of explicit when-not-to-use guidance, and it describes UK postcode expansion behavior without naming the overlapping sibling expand_uk_postcode, leaving the agent to guess between the two.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the connected API key's remaining credit balances (validation, geocode, email, phone pools; trial expiry; the UK free-trial PAF counter for trial keys). Free — never consumes credits.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses that the tool is free and never consumes credits, which is critical for a balance-checking tool. It does not mention authentication or rate limits, but the behavior is straightforward given no parameters.
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 a single sentence that front-loads the main action. It lists multiple balance types, making it slightly verbose, but it remains concise and efficient.
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 parameterless tool with no output schema, the description explains what balances are shown. It could mention the output format (e.g., JSON), but it sufficiently covers the tool's purpose and behavior.
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?
There are zero parameters, and schema coverage is 100%. The description adds full meaning by explaining what the tool reports, so no parameter details are needed.
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 specifies the action 'Show the connected API key's remaining credit balances' and enumerates the specific pools (validation, geocode, email, phone; trial expiry; UK free-trial PAF counter). This distinguishes it from sibling tools which perform enrichment, geocoding, or validation.
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 implies usage for checking balances before operations, but no explicit when-to-use or alternatives are given. It does not state when not to use or compare with siblings, leaving usage guidance implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Address → census & geographic codes (USA + Canada), FREE with validation.
USA: state & county FIPS, census tract (11-digit GEOID), block group,
CBSA/MSA, congressional district (119th Congress), school district.
Canada: province, census division, dissemination area, census subdivision,
census tract, CMA/CA, federal electoral district. Sources: US Census
Bureau TIGER/Line; Statistics Canada (open data).
The enrichment is attached when the address resolves to a house-number- or
street-accurate match; centroid-only matches return no enrichment (the
point could fall in the wrong area). `country` must be "usa" or "can".
The verdict reads as in validate_address (partial_match: true and no
`status` = partially matched, not confirmed).
Cost: 1 validation credit (the enrichment itself is free), same rule as
validate_address; failed lookups are refunded.| Name | Required | Description | Default |
|---|---|---|---|
| city | No | ||
| state | No | ||
| street | No | ||
| country | Yes | ||
| postcode | No | ||
| address_line | No | ||
| house_number | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does most of it: it discloses the cost model (1 validation credit, enrichment free), the refund rule for failed lookups, the match-quality gating that determines whether enrichment appears, and the parse semantics of the returned verdict. It does not mention auth requirements or rate limits, which keeps it from a 5.
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 lead line is front-loaded and the USA/Canada breakdown is scannable, with behavioral caveats and cost placed after the capability statement. It is dense but efficient; the source attribution line is the one element that doesn't strictly help an agent decide or invoke.
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 tool with no output schema and no annotations, the description covers the two things an agent most needs: what fields come back and when they will come back empty. The remaining gap is input assembly — which address fields to populate in what combination — which is not addressed.
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 0%, so the description must compensate, and it does so only partly. It adds a genuinely important constraint absent from the schema — `country` must be "usa" or "can" — but the other six parameters (notably the ambiguity between `address_line` and the `house_number`/`street` pair) are left entirely unexplained.
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?
Names a specific verb-like operation (address → census/geographic enrichment) and enumerates the exact codes returned for both the USA and Canada, so an agent can distinguish it immediately from validate_address and geocode_address. The two-country scope and field list leave no ambiguity about what the tool produces.
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 key usage condition clearly: enrichment is only attached when the address resolves to house-number- or street-accurate matches, and centroid-only matches return nothing. It also pins the accepted `country` values. It stops short of explicitly routing the agent to validate_address or geocode_address when only validation or coordinates are needed, so no exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Expand a UK postcode into every Royal Mail delivery point at that postcode — organisation, building, street, town, county, plus UDPRN, UPRN and rooftop coordinates for each address.
Cost: 1 credit per postcode, regardless of how many addresses come back;
an unknown/invalid postcode is refunded automatically.| Name | Required | Description | Default |
|---|---|---|---|
| postcode | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses cost (1 credit), refund policy for invalid postcodes, and the type of data returned (UDPRN, UPRN, coordinates). This adequately conveys safe, read-only behavior. Could add rate limits or pagination if applicable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence states the verb and resource; the second provides cost details. Front-loaded and efficient.
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 tool with one parameter and no output schema, the description covers purpose, return fields, cost, and refund policy. Could optionally detail output format, but not essential.
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 single parameter 'postcode' has 0% schema description coverage. The tool description explains its role and what the expansion yields, adding meaning beyond the bare schema. Could specify expected format (e.g., full UK postcode with space).
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 expands a UK postcode into delivery points, listing specific fields. It distinguishes from sibling tools like geocode_address or validate_address by explicitly focusing on UK postcode expansion.
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?
No explicit guidance on when to use this tool versus alternatives like enrich_us_ca_address or geocode_address. Usage is implied by the tool name and description, but lacks direct comparison or when-not scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Forward-geocode an address to coordinates (lat/lng) with an explicit accuracy_type — you always know what you got.
accuracy_type is an OPEN set; new tiers are added as reference data
improves. Do NOT write code that treats an unrecognised value as a failure.
Branch on the boolean `point_coordinate` instead, which is true when the
coordinate identifies one address. Current values: rooftop and
arrival_point (both point coordinates — a point on the building, or the
property's entrance / access point), then street_interpolated,
street_centroid, postcode_centroid, locality_centroid, admin_centroid.
House-number-level matches may ALSO carry `arrival_point: {lat, lng}` —
the premise's entrance/access coordinate beside the served pin (equal to
lat/lng when accuracy_type is arrival_point). Use it for delivery and
navigation; omitted when not on file.
`country` is ISO-3 lowercase. Give fielded parts or a single line in `q`.
For UK (gbr) addresses use validate_address instead — it returns point
coordinates from Royal Mail PAF.
A geocode result is a coordinate, not a verdict: it carries no `status`
and no partial_match. accuracy_type says only where the pin is; to tell
the user whether the address itself is valid, use validate_address.
Cost: 1 credit per successful geocode; failures are refunded. A result
whose only location is the state or province (admin_centroid) is not
charged and carries charged: false.| Name | Required | Description | Default |
|---|---|---|---|
| q | No | ||
| city | No | ||
| state | No | ||
| street | No | ||
| country | Yes | ||
| postcode | No | ||
| house_number | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so: it discloses cost (1 credit per successful geocode, failures refunded), the free admin_centroid case with charged:false, the open-set nature of accuracy_type, and the arrival_point supplementary coordinate. It also states what the result does NOT contain (no status, no partial_match).
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 core purpose and the accuracy_type branching rule are front-loaded, and every paragraph adds actionable information. It is somewhat long for a single tool, and the accuracy_type enumeration could be tightened, but nothing is redundant.
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 fully documents the return shape: lat/lng, accuracy_type tiers, the optional arrival_point object and its semantics, and the charged flag. Combined with the UK/validation routing, an agent has everything needed to call and interpret 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?
Schema coverage is 0%, so the description must compensate, and it does for the two most ambiguous params: `country` must be ISO-3 lowercase, and `q` accepts either a single line or fielded parts. The remaining five fielded parts (city, state, street, postcode, house_number) are left to their self-evident names, with no format guidance for postcode or house_number.
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+resource+output: 'Forward-geocode an address to coordinates (lat/lng)'. The word 'forward' implicitly separates it from the sibling reverse_geocode, and the accuracy_type emphasis signals a distinguishing feature of this tool.
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 explicitly routes the agent elsewhere in two concrete cases: 'For UK (gbr) addresses use validate_address instead' and 'to tell the user whether the address itself is valid, use validate_address'. It also says what NOT to do (don't treat unrecognised accuracy_type as failure; branch on point_coordinate).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get an instant FREE Acuris evaluation API key — 1,000 lookups (address validation and geocoding together) plus 50 UK lookups, valid 30 days, no card, no signup form. Idempotent: asking again with the same email within 24h returns the SAME key.
BEFORE calling with accept_terms=true you MUST show the user both links
and get their explicit confirmation that they agree:
Terms of Service: https://api.acuris-geo.com/legal/terms
UK PAF Evaluation Terms: https://api.acuris-geo.com/legal/uk-evaluation-terms
Never set accept_terms=true on the user's behalf without that confirmation.
Without it the tool mints nothing and returns these links.
After receiving the key, reconfigure this MCP server connection with the
header "Authorization: Bearer <key>" (or set ACURIS_API_KEY for stdio).
UK (Royal Mail PAF) lookups are capped at 5 per UTC day while the key is
valid. Paid plans:
https://www.acuris-geo.com/acuris-pricing/| Name | Required | Description | Default |
|---|---|---|---|
| Yes | |||
| accept_terms | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description carries the full burden well: it discloses idempotency (same email within 24h yields the same key), the UK PAF cap of 5 per UTC day, the 30-day validity, and the post-call requirement to reconfigure the connection with a Bearer header or ACURIS_API_KEY. These are non-obvious operational traits an agent could not infer from the name or schema.
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 offer and its limits, then the mandatory confirmation sequence, then post-call setup, so the reading order matches the invocation order. It is dense but nearly every line constrains behavior; the trailing paid-plans URL is the only element that does not serve correct invocation.
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 annotations and no output schema, the description still covers what the caller receives, validity window, idempotency, rate caps, the failure mode when terms are not accepted, and how to use the returned key. Nothing an agent needs to call 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 0%, so the description must supply all parameter meaning, and it does: accept_terms is tied to a concrete validation behavior (false returns terms links and mints nothing) and email is characterized as the idempotency key. Only minor gaps remain, such as no note on email format or whether a different email issues a separate key.
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 (issue a free evaluation API key) with concrete scope: 1,000 combined validation/geocoding lookups plus 50 UK lookups, valid 30 days. It is unmistakably distinct from every sibling, which are all address-operation tools, so an agent can rule it in or out 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?
Gives an explicit precondition sequence (show ToS and UK PAF terms links, obtain explicit user confirmation) and an explicit prohibition ('Never set accept_terms=true on the user's behalf'). It also states what happens when the condition is unmet ('mints nothing and returns these links') and points to paid plans as the out-of-scope alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Coordinates → nearest address(es). Returns the closest reference addresses to (lat, lng), nearest first, with distances.
Optional: `country` (ISO-3) to constrain the search, `radius_m`, `limit`.
Cost: 1 credit per successful lookup; an empty radius (no addresses found)
is refunded.| Name | Required | Description | Default |
|---|---|---|---|
| lat | Yes | ||
| lng | Yes | ||
| limit | No | ||
| country | No | ||
| radius_m | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that it returns nearest addresses with distances and reveals cost behavior ('1 credit per successful lookup; an empty radius is refunded'). However, it lacks details on error handling or rate limits.
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 extremely concise (3 sentences) with no wasted words. It front-loads the primary purpose first, then lists optional parameters, and ends with cost details. Every sentence is necessary and informative.
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?
Given no annotations or output schema, the description covers the essential purpose, parameters, and cost. However, it does not describe the return structure (e.g., address format, fields) or error cases, leaving a gap for a fully complete context.
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?
Despite 0% schema coverage, the description adds substantial meaning for all 5 parameters: it explains the purpose of lat/lng (input coordinates), and clarifies that country is ISO-3, radius_m is in meters, limit controls count. It also provides cost information not in schema.
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 converts coordinates to nearest addresses, with distances, distinguishing it from sibling tools like geocode_address (forward geocoding) and validate_address (validation). It uses a specific verb and resource ('Coordinates → nearest address(es)').
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 provides context for use by explaining optional parameters (country, radius_m, limit) that constrain the search, but does not explicitly state when not to use or compare with alternatives like geocode_address or validate_address. The sibling names imply different use cases, but no direct guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate and standardize one postal address (240+ countries; UK via the official Royal Mail PAF with UDPRN + UPRN).
Give `country` as ISO-3 lowercase (e.g. usa, can, deu, gbr) plus EITHER a
free-text `address_line` OR fielded parts (street, house_number, city,
state, postcode). Returns an honest verdict — status "verified" (exact) or
"corrected" (fixed), or partial_match with reasons — plus the standardized
form, confidence, coordinates with an explicit accuracy_type, and, for
street-accurate USA/Canada matches, a FREE `enrichment` block (census
tract, block group, FIPS, CBSA/MSA, congressional district, school
district / Canadian equivalents).
Reading the verdict: `status` is only ever "verified" or "corrected". A
partial result has partial_match: true and NO `status`: the address was
not fully confirmed. Present it as "partially matched", with `reasons`
(e.g. house_number_unconfirmed, street_not_matched), `deliverable` and the
accuracy_type of the coordinate; never as valid, never as not found.
http_status 404 = not found.
Cost: 1 validation credit per successful lookup (verified, corrected, or a
partial result with a coordinate). No-match, errors and state/province-only
results are not charged: they are refunded automatically (you pay for
results, not attempts).| Name | Required | Description | Default |
|---|---|---|---|
| city | No | ||
| state | No | ||
| street | No | ||
| country | Yes | ||
| postcode | No | ||
| address_line | No | ||
| house_number | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so: it explains that `status` is only 'verified' or 'corrected', that partial results have partial_match:true and NO status, that http_status 404 means not found, and it prescribes how to phrase partial results. It also discloses the billing model (1 credit per successful lookup, auto-refund for no-match/errors/state-only) and the presence of coordinates with accuracy_type plus a free enrichment block.
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 action and the input contract, then the verdict-reading rules and cost. Dense and mostly earned, though the closing clause 'you pay for results, not attempts' restates the preceding refund sentence and the partial-match paragraph is somewhat long relative to its content.
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, and the description covers the return shape thoroughly: status values, partial_match flag, reasons, deliverable, confidence, coordinates with accuracy_type, and the enrichment block. Combined with error semantics (404) and billing, an agent has everything needed to call and interpret 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?
Schema description coverage is 0%, so the description must compensate: it specifies the ISO-3 lowercase format for `country` and enumerates every fielded alternative (street, house_number, city, state, postcode) along with the either/or constraint against `address_line`. It does not define per-field semantics for non-US countries (e.g. what `state` means for a German address) or postcode formats, leaving a small gap.
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 ('Validate and standardize one postal address') and the word 'one' implicitly separates it from the validate_addresses_batch sibling. The scope (240+ countries, UK via Royal Mail PAF with UDPRN/UPRN) makes the tool identifiable 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?
Gives clear operating context: country must be ISO-3 lowercase, and the caller must supply EITHER address_line OR fielded parts, which resolves the main invocation ambiguity. It also states the cost/refund model so the agent knows when calls are free. It never routes explicitly to siblings like autocomplete_address or geocode_address, so it stops 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.
Validate up to 50 addresses in one call (mixed countries allowed).
`addresses` is a list where each entry is either a free-text string, or an
object {"input": <string or fielded object>, "country": "iso3"}. Entries
without their own country use the `country` parameter. UK (gbr) rows are
routed individually to the Royal Mail PAF service; everything else goes
through the batch endpoint. Results come back in the same order, each with
the same shape as validate_address: a row with partial_match: true and no
`status` is partially matched (not confirmed; not valid, not not-found).
Cost: 1 validation credit per successfully validated row (same rule as
validate_address); failed rows are refunded. For files bigger than 50 rows,
call this tool repeatedly.| Name | Required | Description | Default |
|---|---|---|---|
| country | No | ||
| addresses | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden and does so well: it explains routing behavior for UK rows, result ordering, how partial matches are represented, and the credit/refund model. This is unusually rich behavioral context for a batch validation 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?
The description is front-loaded with the core action and cap, then moves through input shape, routing, result semantics, and cost. Each paragraph adds distinct operational value, and there is no redundant restatement of the tool name.
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 compensates by explaining result order and the shape of returned rows, including the `partial_match` flag. Combined with the input-shape and cost details, an agent has what it needs to call this tool 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 0%, so the description must compensate, and it does: it explains that each `addresses` entry may be a free-text string or an object with `input` and `country`, and that entries without a country fall back to the `country` parameter. That is exactly the missing schema semantics an agent needs.
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 ('Validate up to 50 addresses in one call') and explicitly scopes the tool with mixed-country support and a 50-row cap. It also distinguishes this batch tool from the singular sibling by saying results have 'the same shape as validate_address', so the agent can route correctly.
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 clear operational guidance for inputs larger than 50 rows ('call this tool repeatedly') and explains that UK rows are routed automatically to a separate service. It does not explicitly say when to prefer validate_address instead of batching, but the single-vs-batch distinction is strongly implied.
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.
autocomplete_addressrequest_trial_key1 field changedInput schema / properties / accept_termsAdded value: +{
+ "default": false,
+ "title": "Accept Terms",
+ "type": "boolean"
+}check_balanceenrich_us_ca_addressexpand_uk_postcodegeocode_addressrequest_trial_keyreverse_geocodevalidate_addressvalidate_addresses_batchHosted libpostal: messy free-text postal addresses → structured fields. No 2-4GB self-host.
Multi-carrier shipping for AI agents: compare rates, buy labels, track packages, validate addresses
140+ data APIs for agents: finance, banking validation, geo, weather, text. One API key.
Validate emails (MX, disposable, role, typo) and phone numbers, singly or in batches, for AI agents.
Add one secure layer between your agents and this server.
