Address validation & geocoding for AI agents: 240+ countries, UK PAF, free US/CA enrichment
Scored across 9 tools
Tools have mostly distinct purposes (autocomplete, geocode, reverse geocode, validate, expand UK postcode, etc.), but enrich_us_ca_address overlaps with validate_address since the latter already returns a free enrichment block for USA/Canada. This could cause minor uncertainty about when to use each.
All tool names use consistent snake_case with a clear verb_noun or verb_noun_phrase pattern (e.g., validate_address, validate_addresses_batch, geocode_address, reverse_geocode). No mixing of conventions.
9 tools is well-scoped for an address validation and geocoding service, covering single/batch validation, autocomplete, geocoding, reverse geocoding, enrichment, UK postcode expansion, balance check, and trial key retrieval without redundancy.
The surface covers core address lifecycle operations well, but batch geocoding is absent (only single geocode), and despite check_balance mentioning email/phone credit pools, no tools exist for email or phone validation. These are minor gaps that agents can partially work around by repeated calls or may need to avoid.
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".
Cost: 1 validation credit (the enrichment itself is free); 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, the description discloses key behavioral traits: enrichment only on accurate matches, not centroid; cost structure of 1 validation credit with refund on failure. This is comprehensive for a tool with no 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 well-structured with a brief overview, a bullet-like list of codes for each country, and separate paragraphs for match requirements and cost. Every sentence adds value without redundancy.
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 7 parameters, no output schema, and no annotations, the description covers purpose, constraints, and cost but lacks parameter descriptions and output format details. It mentions enrichment is attached but doesn't describe the return structure, which is needed since no output schema exists.
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%, but the description only mentions that country must be 'usa' or 'can'. Other parameters (city, state, street, postcode, address_line, house_number) are listed in schema but not described in the description. The description implies address_line or street+house_number are needed for accurate matches, but doesn't clarify their roles or formatting.
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 that the tool enriches an address with census and geographic codes for USA and Canada, listing specific codes for each country. It differentiates from sibling tools like geocode_address by specifying it returns census/geographic codes, not just coordinates.
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 clear context: enrichment is only for USA and Canada, requires house-number- or street-accurate match, and country must be 'usa' or 'can'. It doesn't explicitly compare to siblings or state when not to use, but the purpose is distinct enough.
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.
Cost: 1 credit per successful geocode; failures are refunded.| 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, description carries full burden. It discloses open accuracy_type set, instructs to branch on point_coordinate, explains arrival_point semantics, and states cost/refund behavior. This is rich behavioral context beyond what annotations would typically provide.
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?
Well-structured, front-loaded with the core purpose, then flows logically into accuracy_type, input guidance, UK alternative, and cost. Every sentence adds meaningful detail; no filler or redundant schema repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains key response concepts (accuracy_type values, point_coordinate boolean, arrival_point). It covers cost, input methods, country format, and sibling-tool avoidance. For a geocoding tool with no annotations, this is highly complete.
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 has 7 params with zero descriptions, so the text must compensate. It explains country as ISO-3 lowercase and clarifies q vs fielded parts. It also describes arrival_point return object and house-number semantics. Does not individually describe city/state/street/postcode, but they are self-explanatory.
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?
Description opens with a specific verb+resource: 'Forward-geocode an address to coordinates (lat/lng)'. It also notes the explicit accuracy_type, clearly distinguishing from reverse_geocode and UK-specific validate_address 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?
Explicitly tells when not to use: 'For UK (gbr) addresses use validate_address instead'. Also gives input formatting alternatives ('fielded parts or a single line in q') and mentions the credit cost, which helps budget-sensitive agents decide when to call.
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 trial API key — 100 credits, valid 7 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 and the free UK
evaluation runs 90 days from acceptance. 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?
With no annotations, the description carries the full burden and does so: idempotency window (same email within 24h returns the SAME key), the guardrail that the tool mints nothing without confirmed terms, the UK PAF cap of 5 lookups per UTC day, the 90-day evaluation window, and the required post-call auth reconfiguration. These are exactly the non-obvious traits an agent needs.
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 value proposition, then the mandatory consent workflow, then operational limits and next steps. Every block is actionable, though the multi-paragraph form is longer than strictly necessary for a two-parameter tool.
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 two important return cases (a key, or the legal links when consent is missing) plus downstream configuration. It stops short of describing response shape or error handling for a malformed email, which an agent would otherwise have to discover at call time.
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 largely does: accept_terms is fully explained (must be true only with user confirmation, otherwise the tool returns links), and email's idempotency semantics are stated. It adds no format guidance for email and does not restate the default of accept_terms=false, keeping it short of a 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 (get a free Acuris trial API key) with scope qualifiers (100 credits, 7 days, no card/signup). It is unmistakably distinct from every sibling tool, which are all address/geocoding utilities.
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 explicit preconditions for use: you MUST show the user both legal links and obtain explicit confirmation before setting accept_terms=true, and it names the fallback behavior (returns links, mints nothing) when that confirmation is absent. It also tells the caller what to do after receiving the key (reconfigure the connection with the Bearer header or ACURIS_API_KEY).
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).
Cost: 1 validation credit per successful lookup; no-match and errors 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?
Since no annotations are provided, the description fully covers behavioral traits including return statuses (verified, corrected, partial_match), standardized form, confidence, coordinates with accuracy type, and free enrichment for US/CA matches. Cost and refund policy are also disclosed.
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 well-structured with key details front-loaded. It is appropriately sized, with each sentence providing useful information. Minor verbosity in listing countries 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?
Given the tool's complexity and no output schema, the description covers input formats, output verdicts, enrichment details, geographic scope, and pricing. It is complete for effective tool selection and 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 0%, so the description must explain parameters. It explains country format and the choice between address_line and fielded parts (city, state, street, house_number, postcode). This adds significant value beyond the raw 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 it validates and standardizes one postal address for 240+ countries, with specific mention of UK via Royal Mail PAF. It distinguishes from sibling tools like enrich_us_ca_address and validate_addresses_batch.
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 explains how to provide input (country as ISO-3 lowercase plus either address_line or fielded parts) and cost model (pay per successful lookup). However, it does not explicitly state when to use this tool versus alternatives, nor when not to use it.
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.
Cost: 1 validation credit per successfully validated row; 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?
Discloses cost (1 credit per successful validation, refunded for failures), result ordering, shape matching validate_address, and routing logic. No annotations are present, so description fully carries 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?
Starts with a clear lead sentence, then uses a structured list format (though plain text) to explain parameter details, cost, and routing. Every sentence is informative and concise.
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?
Covers all needed aspects: limit, mixed countries, cost, routing, result format, and how to handle larger files. No output schema, but result shape is referenced to validate_address. Sibling tools provide 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?
Adds crucial meaning beyond the bare schema: addresses can be strings or objects with 'input' and 'country', and the 'country' parameter serves as default. Schema coverage is 0%, but description completely compensates.
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 validates up to 50 addresses in one call with mixed countries allowed, differentiating it from single-address tool validate_address and other sibling 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?
Provides explicit when-to-use guidance: for up to 50 addresses, mixed countries, and repeat calls for larger files. Also indicates routing behavior for UK addresses vs others.
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.
