Workflow walkthrough · AI agents

Entity due diligence as a tool call

Scenario: an agent is asked to vet a potential vendor — "before we sign with notify-hq.com, what third parties would our data flow through?" That question is answerable entirely from the entity's own subprocessor disclosure. This walkthrough shows the full loop: provisioning, the tool call, and the out-of-credits path.

Step 1 — The agent provisions itself

No dashboard, no verification click. One POST returns a key with 25 free credits:

Self-provisioning

POST https://vendorradar-production.up.railway.app
/v1/keys
Content-Type: application/json

{"email": "agent-runs@yourco.com"}

→ 201 Created
{
  "api_key": "vr_live_8f4b2c91d3e7a650",
  "credit_balance": 25,
  "note": "Key shown once. Store it now."
}

Step 2 — Register the tool

The tool definition lives on the skills page (Anthropic and OpenAI formats). The two lines that matter are in the description, because the model makes the spending decisions: expect live scans to take time, not money (every lookup is 1 credit flat), and never read found: false as "no vendors". Or skip hand-wiring entirely: fetch vendorradar-production.up.railway.app /skill and drop it into .claude/skills/vendorstacks/SKILL.md.

Step 3 — The tool call

Agent tool call

{
  "name": "vendorstacks_check_entity",
  "input": { "url": "notify-hq.com" }
}

Tool result (sample, trimmed)

{
  "domain": "notify-hq.com",
  "found": true,
  "disclosure_url": "https://notify-hq.com/legal/subprocessors",
  "vendor_stack": {
    "sms_messaging": [{
      "vendor": "twilio",
      "confidence": "vendor_keyword",
      "evidence": {
        "source": "https://notify-hq.com/legal/subprocessors",
        "quote": "Twilio Inc. — SMS and voice message delivery"
      }
    }],
    "cloud_infra": [{ "vendor": "aws", "confidence": "vendor" }],
    "email": [{ "vendor": "sendgrid", "confidence": "vendor" }]
  },
  "credits_used": 1,
  "credit_balance": 24
}

The agent's answer can now cite its sources: "Your data would flow through Twilio (SMS), SendGrid (email), and AWS (infrastructure), per the subprocessor list at notify-hq.com/legal/subprocessors, which states: 'Twilio Inc. — SMS and voice message delivery'." Every clause is verifiable at the source URL — extraction is deterministic, so the agent's stochastic layer is the only one you need to audit.

Step 4 — Running out of credits, gracefully

Eventually a lookup will cost more than the key holds. The API answers with a machine-readable 402 and charges nothing:

402 → human handoff

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

# Agent surfaces to the human:
"I need 1 credit for this lookup (balance: 0).
 Top up here: https://vendorstacks.com/pricing — then say 'retry'."

The human gets a ten-second decision instead of a stack trace, and the retry is idempotent.

Cost-discipline rules worth encoding

Every lookup is 1 credit flat — budget wall-clock time (15–90s) for unindexed domains, and force re-scans only on explicit request.
Check /v1/balance (free) at the start of long runs; check /v1/pricing (free) before quoting costs to the human.
Batch reverse lookups by page — 10 entities per credit — instead of checking domains one by one when the question is "who uses X?".

Full endpoint semantics are in the API reference; the install snippets and tool JSON are on the skills page.