DEV Community: hexadata

15 deterministic tools your AI agent should call instead of guessing

hexadata — Thu, 29 Oct 2026 19:09:40 +0000

Ask an LLM whether EKU9003173C9 is a valid Mexican RFC, what the German VAT rate was on a given date, or which HTS code applies to a stainless steel sink, and you get a confident answer. Sometimes it is right. For an invoicing, KYC or customs agent, "sometimes" is not good enough: a check digit is either correct or not, a tariff code is either in the official schedule or not, and a payroll withholding comes from a published table, not from a model's memory.

This post is about the class of work an agent should delegate to deterministic tools and how we packaged 15 of them as one MCP server on Apify. Everything runs against official or open sources, has no LLM inside, stores nothing, and costs half a cent per call.

What belongs in a tool, not in a prompt

Three tests. If the answer (1) has a published algorithm or table, (2) is needed many times per task (one call per invoice, supplier, shipment or employee) and (3) is expensive to get wrong, it belongs in a tool. Business validation passes all three:

Tool	Use this when…	Official source
`validate_tax_id`	checking a company or taxpayer ID from MX, ES, AR, CL, CO, BR, GB, US, IT, FR, DE, PE, CA, AU or IN	check-digit algorithms published by each tax authority
`validate_vat_eu`	confirming an EU VAT number is registered (reverse charge)	VIES, European Commission
`validate_iban`	validating an IBAN and splitting bank, branch and account	ISO 13616 + IBAN registry
`lookup_lei`	finding the legal entity behind an LEI, or the LEI of a name	GLEIF
`lookup_postal_code`	resolving a postal code to city/region/coordinates in 120+ countries	GeoNames (CC BY)
`validate_bank_account`	checking a Mexican CLABE, a US ABA routing number or a SWIFT/BIC	Banxico SPEI list, ABA rules, ISO 9362
`normalize_phone`	storing a phone as E.164 with country and line type	libphonenumber
`validate_email_domain`	checking syntax and whether the domain receives mail (MX, disposable)	DNS + open blocklist
`get_fx_rate`	converting with an official rate for a date	ECB reference rates, Banxico FIX
`business_days`	adding business days or listing holidays in 200+ countries	Nager.Date, Mexican LFT art. 74
`lookup_industry_code`	classifying an activity with NAICS, NACE, CPV or SCIAN	Census, Eurostat, EU Publications Office, INEGI
`lookup_hs_code`	finding a customs tariff code and the US duty rate	USITC HTS, EU Combined Nomenclature
`get_vat_rates`	getting standard and reduced VAT/GST rates of 35 countries for a date	TEDB + national laws
`lookup_sat_catalog`	picking a Mexican CFDI 4.0 catalog value (product key, unit, CFDI use, regime)	SAT official workbook
`calc_payroll_mx`	computing Mexican ISR, subsidy, IMSS, Infonavit and net pay	DOF, INEGI, Ley del Seguro Social

Every answer carries the same envelope: ok, the result, source, sourceUrl, sourceDate or tableVersion, and scrapedAt. Items that cannot be answered (INVALID_INPUT, UNSUPPORTED_COUNTRY, SOURCE_UNAVAILABLE) come back with ok: false and are never charged.

Three design rules

Deterministic. No model inside. The same input always gives the same output, except market data (FX rates) that carries its date.
Stateless. A tax ID or a phone number is validated and forgotten. Logs contain counts and error codes only. No lists of people.
Explicit coverage. Every multi-country tool declares its supported countries in its description and returns UNSUPPORTED_COUNTRY (free) for the rest, so the agent knows when not to trust it.

Call it from an MCP client

The Actor runs as a Streamable HTTP MCP server. Add it to Claude Desktop, Cursor, VS Code or any MCP client:

{
  "mcpServers": {
    "hexadata-validation": {
      "url": "https://hexadatalabs--business-validation-tools-mcp.apify.actor/mcp",
      "headers": { "Authorization": "Bearer <APIFY_TOKEN>" }
    }
  }
}

Then ask: "Validate these supplier tax IDs: MX EKU9003173C9, ES B12345674 and BR 11.222.333/0001-81, and tell me which are malformed." The agent calls validate_tax_id once with three items and reports the valid and reason fields instead of guessing.

Call it from n8n, Make or plain HTTP

Batch mode takes { tool, items[], params } and writes one dataset row per item. One HTTP call, synchronous:

curl -s -X POST "https://api.apify.com/v2/acts/hexadatalabs~business-validation-tools-mcp/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tool":"validate_iban","items":[{"iban":"DE89 3704 0044 0532 0130 00"},{"iban":"DE89370400440532013001"}]}'

The second IBAN comes back with valid: false, reason: "INVALID_CHECK_DIGITS". In n8n or Make, use the Apify node with "Run an Actor and get dataset items" and the same JSON.

Python

from apify_client import ApifyClient

client = ApifyClient("<APIFY_TOKEN>")
run = client.actor("hexadatalabs/business-validation-tools-mcp").call(run_input={
    "tool": "calc_payroll_mx",
    "items": [{"monthlyGross": 20000, "riskClass": "I", "year": 2026}],
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["isr"], item["imssEmployee"]["total"], item["net"], item["employerCost"], item["tableVersion"])

Agents without an account: USDC via x402

The Actor runs with limited permissions, so an agent can buy a prepaid Apify token with USDC through a Coinbase Agentic Wallet (x402) and call it with no Apify account. $1 USDC ≈ 200 single calls or 500 batch items.

What it costs

$0.005 per single-item call, $0.002 per item when a call carries 2–500 items. 1,000 IBAN checks ≈ $2; 5,000 supplier tax IDs across 12 countries ≈ $10; 100 Mexican payroll calculations ≈ $0.20. Invalid input is free.

What it does not do

It checks formats and check digits, not registries (except VIES and GLEIF, which are live). It does not return bank names for ABA or BIC (those directories forbid commercial redistribution). Text search over code systems is a deterministic word match, not semantic search. It is a calculation aid, not tax advice.

Full documentation, the per-tool input and output fields and the legal notes are on the Actor page. Missing a country or a catalog? Open an issue with the official source and we add it.

Public tenders, company registers and business data via API in 5 minutes

hexadata — Thu, 29 Oct 2026 01:44:47 +0000

Most of the data that sales, procurement and research teams need already exists in official, free sources: the EU's tender journal, the US federal contracting portal, the UK company register, the US healthcare provider registry, Mexico's statistical business directory. The problem is never access. It is that every source has its own API quirks, pagination caps, encodings and field names, and nobody wants to maintain seven different clients.

This post shows how we packaged seven of those sources as Apify Actors with one consistent JSON shape, and how to call them from curl, Python, or directly from an AI agent through MCP. Everything below runs against the official sources and is billed per result, so a test costs cents.

What is in the box

Actor	Source	What you get	Price
EU Tenders (TED) Scraper	TED Search API, no key	Contract notices and awards by keyword, country, CPV code, date; buyer, deadline, estimated value	$5.00 / 1,000
SAM.gov Opportunities Scraper	SAM.gov public daily extract, no key	US federal solicitations, sources sought, awards by keyword, NAICS, set-aside, agency, state	$5.00 / 1,000
US Healthcare Providers (NPI Registry) Scraper	NPPES API, no key	Clinics, hospitals, pharmacies, practices by specialty, city, state, ZIP; address, phone, taxonomy	$1.50 / 1,000
UK Companies House Scraper	Companies House API, your free key	Companies and new incorporations by name, SIC code, location, date; profile and officers optional	$2.00 / 1,000 + $1.00 / 1,000 detail requests
Mexico Business Directory (DENUE / INEGI)	INEGI DENUE API	5M+ Mexican establishments with activity, size, address, GPS	$2.00 / 1,000
OCC Mundial Jobs Scraper	occ.com.mx	Mexican job listings with salary, company, work mode	$1.50 / 1,000
Sección Amarilla Mexico Business Scraper	seccionamarilla.com.mx	Mexican businesses with phone, WhatsApp, website, hours	$5.00 / 1,000

Three design rules apply to all of them:

Same field names. id, title or name, url, country, publishedAt, scrapedAt, and typed values (numbers as numbers, dates in ISO 8601, currency as its own field, null instead of empty strings). A tender from TED and an opportunity from SAM.gov land in the same table without mapping.
A hard cost cap. maxResults stops the run at exactly that number, and only items saved to the dataset are charged. Duplicates, invalid rows and failed runs cost nothing.
Incremental mode. onlyNewSinceLastRun: true makes the Actor remember what it delivered (a named key-value store in your account), so a daily schedule returns only new tenders, new solicitations or new companies. That is where the recurring value is.

Under the hood each Actor does the boring part: TED's expert query language and 15,000-result window (the Actor switches to iteration mode), SAM.gov's 200 MB Windows-1252 CSV that has to be streamed and stopped early, NPPES's silent 1,200-record cap (the Actor splits the area by ZIP prefix), Companies House's 10,000-result window and 600-requests-per-5-minutes limit (the Actor splits by incorporation date and waits out 429s).

1. curl: open tenders for software in Germany

The simplest way is the synchronous endpoint, which runs the Actor and returns the dataset in one call. Get a token from Apify Console (Settings → API & Integrations); a free account includes monthly usage credit.

curl -X POST "https://api.apify.com/v2/acts/hexadatalabs~eu-tenders-ted-scraper/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"searchQueries":["software"],"countries":["DE"],"noticeTypes":"competition","dateFrom":"2026-10-20","maxResults":50}'

A typical item:

{
  "id": "745163-2026",
  "title": "Germany – Software package and information systems – PolBln 423_26 EU Beschaffung Storagesystem",
  "buyerName": "Polizei Berlin",
  "country": "DE",
  "noticeTypeLabel": "Contract notice",
  "publishedAt": "2026-10-27",
  "deadline": "2026-11-26T07:00:00+01:00",
  "estimatedValue": 1680672.27,
  "currency": "EUR",
  "cpvCodes": ["48000000"],
  "url": "https://ted.europa.eu/en/notice/-/detail/745163-2026"
}

Fifty results cost $0.25.

2. Python: a daily feed of new UK companies with their directors

Install the client (pip install apify-client), create a free Companies House API key (two minutes at developer.company-information.service.gov.uk), and run:

from apify_client import ApifyClient

client = ApifyClient("<APIFY_TOKEN>")
run = client.actor("hexadatalabs/uk-companies-house-scraper").call(run_input={
    "apiKey": "<COMPANIES_HOUSE_KEY>",
    "sicCodes": ["62012", "62020"],        # software development, IT consultancy
    "location": "Manchester",
    "onlyNewSinceLastRun": True,           # first run: everything since 7 days ago; then only new ones
    "includeOfficers": True,
    "maxResults": 500,
})
for company in client.dataset(run["defaultDatasetId"]).iterate_items():
    directors = [o["name"] for o in company.get("officers", []) if o["role"] == "director"]
    print(company["incorporatedAt"], company["name"], company["postalCode"], directors)

Put the same input on an Apify Schedule (every weekday at 08:00) and add a webhook or an integration (Slack, e-mail, Google Sheets, HubSpot) on the run-succeeded event. Each morning you get the companies incorporated the day before, nothing twice. At about 100 companies a day with officers, that is roughly $0.30 per day.

The same pattern works for SAM.gov (naicsCodes + states + onlyNewSinceLastRun) and for TED (cpvCodes + countries).

3. From an AI agent (MCP)

Every Apify Actor is exposed as a tool by the Apify MCP server, so an agent can call these sources directly. Add the server to Claude Desktop, Cursor, VS Code or any MCP client:

{
  "mcpServers": {
    "hexadata": {
      "url": "https://mcp.apify.com?tools=hexadatalabs/eu-tenders-ted-scraper,hexadatalabs/sam-gov-opportunities-scraper,hexadatalabs/us-healthcare-providers-npi-scraper",
      "headers": { "Authorization": "Bearer <APIFY_TOKEN>" }
    }
  }
}

Then ask in plain language:

"Which small-business set-aside solicitations for IT services in Virginia or Maryland were posted this week, and when do they close? At most 100 results."

The agent calls sam-gov-opportunities-scraper with {"naicsCodes":["5415"],"setAsides":["SBA"],"states":["VA","MD"],"noticeTypes":"solicitation","dateFrom":"...","maxResults":100} and answers from the deadline, setAside and url fields. Tool selection works because every Actor description and every input field starts with "Use this when…", which is what the model reads when it picks a tool. Saying "at most N results" in the prompt is the same cost cap as maxResults in code.

In Claude Code the same server is one command:

claude mcp add --transport http hexadata "https://mcp.apify.com?tools=hexadatalabs/uk-companies-house-scraper" --header "Authorization: Bearer <APIFY_TOKEN>"

What about legality and personal data

All seven Actors read official APIs or public pages within their terms, identify themselves, and pace requests. Personal data is opt-in only: Companies House officers (includeOfficers), SAM.gov contracting-officer contacts (includeContacts), NPPES individual practitioners (includeIndividuals), DENUE business contact fields. By default you get organisations, notices and establishments, with the source attribution in every item.

Try it

Each Actor's page on Apify has a "Try for free" input with a cheap prefill, the full field list, cost examples and the MCP snippet: apify.com/hexadatalabs.
The MCP connection guide and server.json are in the hexadata-mcp repository, and the server is listed in the official MCP registry as io.github.4robot/hexadata.
Missing a source (another country's tender portal, another register)? Open an issue on any Actor and say what you need; the next one is usually a clone of an existing one.