# Give your AI agent the VendorStacks tool

> VendorStacks — the subprocessor disclosure data API. Canonical: https://vendorstacks.com
/docs/guides/agent-tool/


Register an entity-due-diligence tool: function-calling definition, cost-discipline rules, and the 402 relay.

VendorStacks is designed to be operated by agents: instant key issuance, deterministic JSON, machine-readable paywalls. The fastest path is the installable skill file at [vendorradar-production.up.railway.app
/skill](https://vendorradar-production.up.railway.app
/skill) — for Claude Code, save it to `.claude/skills/vendorstacks/SKILL.md`. For explicit function-calling, register this tool:

**Tool definition (Anthropic format; for OpenAI rename input_schema → parameters)**

```
{
  "name": "vendorstacks_check_entity",
  "description": "Look up whether an entity (by domain) publishes a subprocessor/DPA disclosure and which vendors it names, as a structured vendor stack with quoted evidence. Every lookup costs 1 credit flat: indexed answers return <1s, unindexed domains live-scan automatically (15-90s, same price) — use a 120s timeout. fresh=true forces a re-scan at the same price. found=false means no disclosure was located, NOT that the entity uses no vendors.",
  "input_schema": {
    "type": "object",
    "properties": {
      "url": { "type": "string", "description": "Domain, e.g. acme.com" },
      "fresh": { "type": "boolean", "description": "Force live re-scan. Default false." }
    },
    "required": ["url"]
  }
}
```

### The two rules that belong in the description

- **Budget time, not just credits.** Every lookup is 1 credit, so the model can't overspend per call — but `fresh=true` and unindexed domains take 15–90s each. The description tells the model to expect the wait and to re-scan only on explicit request.
- **`found: false` ≠ "no vendors".** An agent that reports "this company uses no third parties" off a found:false is confidently wrong. Spell out the correct reading.

### The 402 relay

**Handler with human handoff**

```
async function vendorstacks_check_entity({ url, fresh = false }) {
  const res = await fetch(
    `https://vendorradar-production.up.railway.app
/v1/check?url=${encodeURIComponent(url)}` + (fresh ? "&fresh=true" : ""),
    { headers: { Authorization: `Bearer ${process.env.VENDORSTACKS_KEY}` } },
  );
  if (res.status === 402) {
    const { topup_url, credits_needed, remaining_credits } = await res.json();
    return {
      needs_human: true,
      message: `Need ${credits_needed} credits (have ${remaining_credits}). Top up: ${topup_url}`,
    };
  }
  return await res.json();
}
```

The human gets a ten-second decision instead of a stack trace; nothing was charged and the retry is idempotent. More on the paywall in [Handle 402s gracefully](/docs/guides/handle-402s); install snippets and the OpenAI-format JSON live on the [skills page](/skills).