LLM Tool Calling with REST APIs in Node.js and Python

The earlier courses in this certification connected agents to APIVerve over MCP: an assistant discovers the tools, calls them, and you watch. That is the right shape for a person chatting with a model. It is the wrong shape for a backend job that runs at 3am with nobody watching, because the client decides how the loop runs, and you want to decide.

So this course drops one level. You will call a model's API directly, hand it a short list of tools built from APIVerve endpoints, and run the tool-use loop in your own server code. The model never sees your API key and never makes an HTTP request. It asks for a call; your code decides whether to make it, makes it, and hands back the result.

By the end of this lesson you will have three small files you reuse for the rest of the course: a catalog of tool definitions, an executor that turns a tool call into a REST request, and a loop that drives a model until it has an answer.

What a tool call actually is

Strip away the vocabulary and tool use is a structured conversation with four moves:

You send the model a prompt plus a list of tools. Each tool is a name, a description and a JSON Schema for its input.
The model replies either with text (it is done) or with one or more tool calls: a tool name plus an input object that should match the schema.
Your code runs each call and sends the results back, tagged with the id of the call they answer.
Repeat until the model replies with text, or until you stop it.

Every vendor that supports tool calling uses this shape. The field names differ (input_schema here, parameters there; tool_use blocks in one API, tool_calls in another), but the loop is identical. That is why the code below keeps everything except one function vendor-neutral: the catalog, the schema builder and the executor know nothing about which model you use. Only the loop speaks one vendor's wire format, and swapping vendors means rewriting about forty lines.

The examples use Anthropic's Messages API through its official SDK, because its request and response shapes are documented and stable. If you use a different provider, keep everything else and port runAgent.

Tool definitions come from the API's own parameters

You could write tool schemas by hand. Don't. Every APIVerve endpoint already publishes its parameters, with names, types, descriptions, examples and which ones are required, on its reference page. Copy them into a small catalog and generate schemas from it, and your tool definitions cannot drift from the API's actual contract.

Start with the APIs the triage agent in lesson 3 will need. Look at what one of them returns:

Try it liveEmail Validator20 credits

GEThttps://api.apiverve.com/v1/emailvalidator

1
2

curl "https://api.apiverve.com/v1/emailvalidator?email=support%40myspace.com" \
  -H "x-api-key: YOUR_API_KEY"

email

Sign in or create a free account to run this with your own key.

isRoleAccount is true and isCompanyEmail is true: this is a shared company mailbox, not a person.

Try it liveIP Lookup10 credits

GEThttps://api.apiverve.com/v1/iplookup

1
2

curl "https://api.apiverve.com/v1/iplookup?ip=173.172.81.20" \
  -H "x-api-key: YOUR_API_KEY"

ip

Sign in or create a free account to run this with your own key.

country, regionName and timezone are on every plan. city, coordinates and asn are premium.

Try it liveVPN Proxy Detector10 credits

GEThttps://api.apiverve.com/v1/vpndetector

1
2

curl "https://api.apiverve.com/v1/vpndetector?ip=103.62.49.210" \
  -H "x-api-key: YOUR_API_KEY"

ip

Sign in or create a free account to run this with your own key.

is_vpn and is_datacenter are on every plan. is_tor and risk_level are premium.

Now write the catalog. This is a trimmed copy of each endpoint's published definition: the same field names, the same structure, only the parts a tool needs.

catalog.json

[
  {
    "id": "emailvalidator",
    "title": "Email Validator",
    "description": "Checks whether an email address is well-formed, whether its domain can receive mail, and whether it is disposable, a role account or a free provider. Returns a normalized address for spotting duplicates.",
    "tokenUse": 20,
    "endpoints": [{
      "method": "GET",
      "parameters": [
        { "name": "email", "type": "string", "description": "The email address to validate", "example": "[email protected]", "required": true }
      ]
    }]
  },
  {
    "id": "iplookup",
    "title": "IP Lookup",
    "description": "Resolves an IP address to its country, region, timezone and continent.",
    "tokenUse": 10,
    "endpoints": [{
      "method": "GET",
      "parameters": [
        { "name": "ip", "type": "string", "description": "The IP address to locate", "example": "173.172.81.20", "required": true }
      ]
    }]
  },
  {
    "id": "vpndetector",
    "title": "VPN Proxy Detector",
    "description": "Checks whether an IP address belongs to a VPN or a cloud datacenter.",
    "tokenUse": 10,
    "endpoints": [{
      "method": "GET",
      "parameters": [
        { "name": "ip", "type": "string", "description": "The IP address to check", "example": "103.62.49.210", "required": true }
      ]
    }]
  }
]

Three things in that file do real work later:

tokenUse is the credit cost per call. You will put it in the tool description so the model can see the price, which is exactly what the APIVerve MCP server does, and in lesson 4 you will use it to enforce a per-run budget.
method tells the executor whether to send a query string or a JSON body. emailvalidator is a GET; the page and text tools in the next lesson are POST.
premium, when a parameter has it, marks an input only some plans accept. The schema builder leaves premium parameters out by default, so the model cannot ask for something your key will not honour.

Build the schemas and the executor

Set up a project. Both languages read the same catalog.json.

mkdir agent-workflows && cd agent-workflows
npm init -y && npm pkg set type=module
npm install @anthropic-ai/sdk
# or, for Python
pip install anthropic requests

export APIVERVE_API_KEY=YOUR_API_KEY
export ANTHROPIC_API_KEY=YOUR_MODEL_PROVIDER_KEY

The tools module has three jobs: build a vendor-neutral tool spec from a definition, run one REST call, and wrap that call so that every outcome, success or failure, becomes something the model can read.

import { readFileSync } from 'node:fs';

const BASE = 'https://api.apiverve.com/v1';
const CATALOG = JSON.parse(readFileSync(new URL('./catalog.json', import.meta.url), 'utf8'));
export const DEFS = new Map(CATALOG.map((d) => [d.id, d]));

// Vendor-neutral: { name, description, schema }
export function toolFromDefinition(def, { includePremium = false } = {}) {
  const properties = {};
  const required = [];
  for (const p of def.endpoints[0].parameters) {
    if (p.premium && !includePremium) continue;
    const example = p.example !== undefined ? ` Example: ${p.example}.` : '';
    properties[p.name] = { type: p.type, description: `${p.description}.${example}` };
    if (p.required) required.push(p.name);
  }
  return {
    name: def.id,
    description: `${def.title}: ${def.description} Costs ${def.tokenUse} credits per call.`,
    schema: { type: 'object', properties, required, additionalProperties: false },
  };
}

export const apiTools = (ids) => ids.map((id) => toolFromDefinition(DEFS.get(id)));

export async function callApiverve(def, input, { timeoutMs = 30000 } = {}) {
  const key = process.env.APIVERVE_API_KEY;
  if (!key) throw new Error('APIVERVE_API_KEY is not set');
  const ep = def.endpoints[0];
  const allowed = new Set(ep.parameters.map((p) => p.name));
  const params = Object.fromEntries(Object.entries(input ?? {}).filter(([k]) => allowed.has(k)));

  let url = `${BASE}/${def.id}`;
  const init = { method: ep.method, headers: { 'x-api-key': key }, signal: AbortSignal.timeout(timeoutMs) };
  if (ep.method === 'GET') {
    url += `?${new URLSearchParams(params)}`;
  } else {
    init.headers['Content-Type'] = 'application/json';
    init.body = JSON.stringify(params);
  }

  const res = await fetch(url, init);
  const body = await res.json().catch(() => null);
  if (!res.ok || body?.status !== 'ok') {
    const outOfCredits = res.status === 429 && res.headers.get('x-api-remaining-credits') === '0';
    return { ok: false, status: res.status, outOfCredits, error: body?.error || `HTTP ${res.status}` };
  }
  return { ok: true, data: body.data };
}

const MAX_RESULT_CHARS = 8000;

// Every outcome becomes { content, isError, fatal? } so the loop never throws mid-turn.
export async function executeApiTool(name, input) {
  const def = DEFS.get(name);
  if (!def) return { content: `Unknown tool "${name}".`, isError: true };
  try {
    const r = await callApiverve(def, input);
    if (r.ok) {
      let text = JSON.stringify(r.data);
      if (text.length > MAX_RESULT_CHARS) text = `${text.slice(0, MAX_RESULT_CHARS)} [truncated]`;
      return { content: text, isError: false };
    }
    const fatal = r.status === 401 || r.status === 403 || r.outOfCredits;
    return { content: `${name} failed (${r.status}): ${r.error}`, isError: true, fatal };
  } catch (e) {
    return { content: `${name} failed: ${e.name === 'TimeoutError' ? 'timed out' : e.message}`, isError: true };
  }
}

import json
import os
from pathlib import Path

import requests

BASE = "https://api.apiverve.com/v1"
CATALOG = json.loads((Path(__file__).parent / "catalog.json").read_text(encoding="utf-8"))
DEFS = {d["id"]: d for d in CATALOG}
MAX_RESULT_CHARS = 8000


def tool_from_definition(d, include_premium=False):
    properties, required = {}, []
    for p in d["endpoints"][0]["parameters"]:
        if p.get("premium") and not include_premium:
            continue
        example = f" Example: {p['example']}." if "example" in p else ""
        properties[p["name"]] = {"type": p["type"], "description": f"{p['description']}.{example}"}
        if p.get("required"):
            required.append(p["name"])
    return {
        "name": d["id"],
        "description": f"{d['title']}: {d['description']} Costs {d['tokenUse']} credits per call.",
        "schema": {"type": "object", "properties": properties, "required": required, "additionalProperties": False},
    }


def api_tools(ids):
    return [tool_from_definition(DEFS[i]) for i in ids]


def call_apiverve(d, args, timeout=30):
    ep = d["endpoints"][0]
    allowed = {p["name"] for p in ep["parameters"]}
    params = {k: v for k, v in (args or {}).items() if k in allowed}
    headers = {"x-api-key": os.environ["APIVERVE_API_KEY"]}
    url = f"{BASE}/{d['id']}"
    if ep["method"] == "GET":
        query = {k: (str(v).lower() if isinstance(v, bool) else v) for k, v in params.items()}
        res = requests.get(url, params=query, headers=headers, timeout=timeout)
    else:
        res = requests.post(url, json=params, headers=headers, timeout=timeout)
    try:
        body = res.json()
    except ValueError:
        body = None
    if not res.ok or not body or body.get("status") != "ok":
        out = res.status_code == 429 and res.headers.get("x-api-remaining-credits") == "0"
        error = (body or {}).get("error") or f"HTTP {res.status_code}"
        return {"ok": False, "status": res.status_code, "out_of_credits": out, "error": error}
    return {"ok": True, "data": body["data"]}


def execute_api_tool(name, args):
    d = DEFS.get(name)
    if d is None:
        return {"content": f'Unknown tool "{name}".', "is_error": True}
    try:
        r = call_apiverve(d, args)
    except requests.RequestException as e:
        return {"content": f"{name} failed: {e}", "is_error": True}
    if r["ok"]:
        text = json.dumps(r["data"])
        if len(text) > MAX_RESULT_CHARS:
            text = text[:MAX_RESULT_CHARS] + " [truncated]"
        return {"content": text, "is_error": False}
    fatal = r["status"] in (401, 403) or r["out_of_credits"]
    return {"content": f"{name} failed ({r['status']}): {r['error']}", "is_error": True, "fatal": fatal}

Read the executor's error handling closely, because it is the part people get wrong.

Failures go back to the model as results, not exceptions. A tool call the model made is a question it is waiting on. If you throw, the whole run dies over something the model might have handled: a typo in an IP address comes back as a 4xx with a readable message, and the model can fix the argument and try again. So a failed call becomes a result flagged isError, and the conversation continues.

Some failures are fatal, and those stop the run. A 401 means the key is missing or unrecognised. A 403 means the key is valid but not allowed this call, from key scoping, an IP allow-list or revocation. A 429 with x-api-remaining-credits: 0 means the month's credits are gone. None of these can be fixed by the model choosing different arguments, and a model that sees "error" tends to retry. The fatal flag lets the loop stop instead of paying for more model turns that cannot succeed. A 429 with credits remaining is the per-minute rate limit, which is transient, so it stays non-fatal.

The executor filters arguments against the definition. APIVerve silently ignores parameters it does not recognise rather than rejecting them, so a model that invents "strict": true would get a normal response and a false belief that its extra argument did something. Dropping undeclared keys before the call keeps the request honest.

Results are capped. A tool result goes into the model's context on every later turn. A large response pasted in whole costs tokens each time and buries the fields that matter. Eight thousand characters is plenty for verification APIs; you will see a better pattern for large page content in the next lesson.

Check yourself

Your agent calls iplookup and gets a 403 with a JSON body. What should the executor do?

Run the tool-use loop

The loop is the only vendor-specific code. It converts the neutral tool specs into the provider's format, sends the conversation, runs any tool calls, and appends the results. It also reports every model turn and tool call to an onEvent callback, which is your logging hook for lesson 4.

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();
const MODEL = process.env.MODEL || 'claude-opus-5-5';

export async function runAgent({ system, prompt, tools, execute, maxTurns = 8, onEvent = logEvent }) {
  const apiTools = tools.map((t) => ({ name: t.name, description: t.description, input_schema: t.schema }));
  const messages = [{ role: 'user', content: prompt }];

  for (let turn = 1; turn <= maxTurns; turn++) {
    const response = await client.messages.create({ model: MODEL, max_tokens: 16000, system, tools: apiTools, messages });
    onEvent({ type: 'model', turn, stopReason: response.stop_reason, usage: response.usage });
    messages.push({ role: 'assistant', content: response.content });

    if (response.stop_reason !== 'tool_use') {
      const text = response.content.filter((b) => b.type === 'text').map((b) => b.text).join('\n');
      return { stopReason: response.stop_reason, text, messages };
    }

    const calls = response.content.filter((b) => b.type === 'tool_use');
    const outcomes = await Promise.all(calls.map(async (call) => {
      const started = Date.now();
      const r = await execute(call.name, call.input);
      onEvent({ type: 'tool', turn, name: call.name, input: call.input, isError: r.isError, ms: Date.now() - started });
      return r;
    }));

    const fatal = outcomes.find((r) => r.fatal);
    if (fatal) return { stopReason: 'fatal_tool_error', text: fatal.content, messages };
    const final = outcomes.find((r) => r.final !== undefined);
    if (final) return { stopReason: 'final', final: final.final, messages };

    messages.push({
      role: 'user',
      content: calls.map((call, i) => ({
        type: 'tool_result', tool_use_id: call.id, content: outcomes[i].content, is_error: outcomes[i].isError,
      })),
    });
  }
  return { stopReason: 'max_turns', text: '', messages };
}

function logEvent(e) {
  console.error(JSON.stringify(e));
}

import json
import os
import sys
import time

import anthropic

client = anthropic.Anthropic()
MODEL = os.environ.get("MODEL", "claude-opus-5-5")


def log_event(e):
    print(json.dumps(e, default=str), file=sys.stderr)


def run_agent(system, prompt, tools, execute, max_turns=8, on_event=log_event):
    api_tools = [{"name": t["name"], "description": t["description"], "input_schema": t["schema"]} for t in tools]
    messages = [{"role": "user", "content": prompt}]

    for turn in range(1, max_turns + 1):
        response = client.messages.create(
            model=MODEL, max_tokens=16000, system=system, tools=api_tools, messages=messages
        )
        on_event({"type": "model", "turn": turn, "stop_reason": response.stop_reason,
                  "input_tokens": response.usage.input_tokens, "output_tokens": response.usage.output_tokens})
        messages.append({"role": "assistant", "content": response.content})

        if response.stop_reason != "tool_use":
            text = "\n".join(b.text for b in response.content if b.type == "text")
            return {"stop_reason": response.stop_reason, "text": text, "messages": messages}

        calls = [b for b in response.content if b.type == "tool_use"]
        outcomes = []
        for call in calls:
            started = time.monotonic()
            r = execute(call.name, call.input)
            on_event({"type": "tool", "turn": turn, "name": call.name, "input": call.input,
                      "is_error": r.get("is_error", False), "ms": round((time.monotonic() - started) * 1000)})
            outcomes.append(r)

        fatal = next((r for r in outcomes if r.get("fatal")), None)
        if fatal:
            return {"stop_reason": "fatal_tool_error", "text": fatal["content"], "messages": messages}
        final = next((r for r in outcomes if "final" in r), None)
        if final:
            return {"stop_reason": "final", "final": final["final"], "messages": messages}

        messages.append({"role": "user", "content": [
            {"type": "tool_result", "tool_use_id": c.id, "content": r["content"], "is_error": r.get("is_error", False)}
            for c, r in zip(calls, outcomes)
        ]})
    return {"stop_reason": "max_turns", "text": "", "messages": messages}

The details that matter:

Append the whole assistant message, not just its text. The tool calls live in response.content. If you append only the text, the next request contains results that answer calls the API never saw, and it is rejected.
All results for one turn go back in one message. A model can ask for several calls at once, for example iplookup and vpndetector on the same address. The Node version runs them concurrently with Promise.all; either way, every result goes into a single user message, each tagged with its tool_use_id.
Any stop reason other than tool_use ends the loop, and the caller has to look at which one. end_turn is a normal answer. max_tokens means the reply was cut off, and refusal means the model declined; neither is an answer your code should act on.
maxTurns is not optional. A loop without a ceiling is a loop that can spend money until someone notices. Eight turns is generous for a job that needs three calls.
A tool can end the run on purpose. If a tool returns a final value, the loop stops and hands it back. You will use that in the next two lessons to get a structured answer instead of free text.

Now run it:

import { runAgent } from './agent.js';
import { apiTools, executeApiTool } from './tools.js';

const result = await runAgent({
  system: 'You answer questions about email addresses and IP addresses using the tools provided. Use a tool rather than guessing. Be brief.',
  prompt: process.argv.slice(2).join(' '),
  tools: apiTools(['emailvalidator', 'iplookup', 'vpndetector']),
  execute: executeApiTool,
});
console.log(result.stopReason, '\n', result.text);

import sys

from agent import run_agent
from tools import api_tools, execute_api_tool

result = run_agent(
    system="You answer questions about email addresses and IP addresses using the tools provided. "
           "Use a tool rather than guessing. Be brief.",
    prompt=" ".join(sys.argv[1:]),
    tools=api_tools(["emailvalidator", "iplookup", "vpndetector"]),
    execute=execute_api_tool,
)
print(result["stop_reason"], "\n", result["text"])

node run.js "Is [email protected] a personal mailbox, and is 103.62.49.210 a residential connection?"

On stderr you will see a model event, then two tool events in the same turn, emailvalidator and vpndetector called in parallel, then a final model event with end_turn. The answer should say the address is a role account at a company domain and the IP is in a datacenter. If the model did not call a tool at all and answered from memory, your system prompt or tool descriptions are not doing their job, which is the first thing lesson 4 tests for.

Check yourself

Your loop appends only the assistant's text to the message history, then sends the tool results. What happens?

Answer the check above to continue.

Choosing which tools to hand over

The catalog has over 300 APIs, and it is tempting to generate tools for all of them. Resist it. Every tool definition is sent with every request, so a long list is a fixed token cost on each turn, and a model choosing among hundreds of similar tools picks the wrong one more often than one choosing among three. The MCP documentation makes the same point about the hosted server: an agent cannot misuse a tool it was never given.

A good rule: if you can name the job, you can name the tools. A signup triage agent needs three. A research agent needs two. Start there and add a tool only when a test case shows the agent needed one it did not have.

Also ask whether a call needs a model at all. If every flagged signup gets an email check, call emailvalidator in plain code before the agent starts and put the result in the prompt. Paying a model to decide something that is already decided adds latency and a failure mode. Save model-chosen tools for the calls that genuinely depend on what earlier results said.

You now have a loop that can call any APIVerve endpoint you describe to it. Next you will build an agent around it that reads web pages, summarises them, and refuses to cite anything it did not actually read: Build a research agent.

Finished the lesson?Mark it complete to track your progress toward the certification.

Next: Build a research agent that cites its sources →

Call APIVerve APIs as tools from your own code

What a tool call actually is

Tool definitions come from the API's own parameters

Build the schemas and the executor

Run the tool-use loop

Choosing which tools to hand over

Run every example on your own key. Free plan, no card.

Scaling up?