Give your AI agent the VendorStacks tool

Markdown mirror: /docs/guides/agent-tool.md

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; install snippets and the OpenAI-format JSON live on the skills page.