Giving your AI agent a due-diligence tool

A useful pattern is emerging in agent design: give the model a small set of narrow, factual tools and let it compose them. "What vendors does this company run?" is exactly that kind of tool — bounded input (a domain), structured output (a vendor stack), verifiable provenance (quoted disclosure rows). We built VendorStacks to slot into that pattern with as little glue as possible. This post walks through the integration, including the parts that usually go wrong: provisioning, cost control, and what the agent should do when it runs out of money.

Provisioning without a human in the loop

Most APIs assume a human signs up, clicks a verification link, and pastes a key into an env var. An agent can't click a verification email. So key issuance here is one POST:

POST https://vendorradar-production.up.railway.app
/v1/keys
{"email": "agent-runs@yourco.com"}

→ 201 { "api_key": "vr_live_…", "credit_balance": 25 }

The key arrives in the same response with 25 free credits attached — enough for an agent to do real work (25 lookups plus reverse lookup) before anyone decides whether to fund it. Store it like the secret it is; it's shown once.

A tool definition that encodes cost discipline

The interesting part of the function-calling definition isn't the schema — it's the description. Two rules belong in the prompt layer because the model, not your code, makes the spending decisions:

• Budget time, not just credits. Every lookup is 1 credit flat, but an unindexed domain (or fresh=true) means a 15–90 second live scan. The description tells the model to expect the wait, use a 120s timeout, and re-scan only when the user explicitly asked.
• found: false ≠ "no vendors". It means no disclosure page was located. An agent that reports "this company uses no third-party vendors" off a found: false is confidently wrong — the description spells out the correct reading so the summary step doesn't invent a fact.

If you'd rather not hand-write any of this, the API serves an installable skill file at vendorradar-production.up.railway.app /skill — for Claude Code, save it to .claude/skills/vendorstacks/SKILL.md and it loads when relevant. There's also llms.txt for orientation and openapi.json if your framework generates tools from specs.

The 402 is the interface between agent and human

Agents run out of credits mid-task. The failure mode to avoid is silent degradation — the agent catches an opaque error, shrugs, and produces a report with holes. So the paywall is designed to be escalated: a 402 with the exact shortfall and a top-up link.

402 Payment Required
{
  "error": "insufficient_credits",
  "required_credits": 10,
  "credit_balance": 3,
  "topup_url": "https://vendorstacks.com/pricing"
}

The right handler is three lines: catch the 402, surface topup_url and the price to the human, pause. Nothing was charged; the retry is idempotent. A human gets a decision that takes ten seconds ("spend $10? yes") instead of a debugging session.

Why determinism matters more inside an agent

An agent is already a stochastic system. Feeding it tools that are themselves stochastic compounds the problem — you can't tell whether a wrong answer came from the model or the data. VendorStacks's extraction has no LLM in the path: the same disclosure always parses to the same stack, and every vendor claim carries the verbatim quote. When your agent cites "Twilio Inc. — SMS and voice message delivery", that sentence exists at the source URL. For due-diligence workflows — vetting a vendor, checking a prospect's stack before a call, screening an acquisition target's dependencies — that auditability is the difference between a tool call and a liability.

The full walkthrough, with a complete agent transcript, is at /use-cases/agent-due-diligence. Wiring it up takes about ten minutes; the first 25 credits are free.