Introduction

AI agents become useful when they can talk to the outside world. REST APIs are the most common way systems expose functionality, so an agent must be able to call them on demand. The challenge is that most APIs are designed for human-driven clients (dashboards, mobile apps), not for autonomous decision-makers. Before an agent can use an API, you need to translate the API contract into something the agent can understand and invoke.

Wrapping an API as a Tool

A tool, from the agent's perspective, is a function with a name, a description, and a set of parameters. You build a thin wrapper that receives structured input from the agent (for example, a city name) and returns a structured result.

import requests

def get_weather(city: str) -> dict:
    url = "https://api.example.com/weather"
    params = {"q": city, "units": "metric"}
    response = requests.get(url, params=params, timeout=10)
    response.raise_for_status()
    return response.json()

The wrapper hides HTTP details (headers, status codes, JSON parsing) and exposes a clean function signature. The agent sees only the function name, its docstring or description, and the typed parameters.

Structuring the Description for the Agent

The description is what tells the agent when and how to call the tool. A good tool description has three parts: a one-line summary of what the tool does, a note on when to use it (and equally important, when not to), and a description of every parameter including format and constraints.

{
  "name": "get_weather",
  "description": "Get current weather for a city. Use when the user asks about weather, temperature, or conditions outdoors. Do not use for forecasts beyond 24 hours.",
  "parameters": {
    "city": {
      "type": "string",
      "description": "City name in English, e.g. 'Hanoi' or 'Tokyo'"
    }
  }
}

Keep descriptions factual. Avoid hype words like "powerful" or "advanced" — the agent makes calling decisions based on utility, not marketing language.

Handling Rate Limits, Pagination, and Errors

APIs fail in predictable ways. Your wrapper must handle those failures so the agent gets useful feedback instead of raw stack traces.

For rate limits, respect the Retry-After header when present and back off exponentially on repeated 429 responses. Wrap the call in a retry loop with a maximum attempt count to avoid infinite waits.

import time
import requests

def call_with_retry(url, params, max_attempts=3):
    for attempt in range(max_attempts):
        response = requests.get(url, params=params, timeout=10)
        if response.status_code == 429:
            wait = int(response.headers.get("Retry-After", 2 ** attempt))
            time.sleep(wait)
            continue
        response.raise_for_status()
        return response.json()
    raise Exception("Rate limited after retries")

For pagination, design the wrapper so it accepts a page or cursor parameter and returns a clear signal when more pages are available. Let the agent decide whether to keep fetching — it can reason about cost and relevance better than a hardcoded loop.

For errors, return a structured object instead of raising exceptions blindly. Include the status code, a short human-readable reason, and optionally a hint on how to recover. This lets the agent retry with corrected parameters, switch tools, or report the problem back to the user.

Summary

Treat every API as a tool with three layers: a clean function signature, a precise description the agent can use for selection, and a robust wrapper that handles the messy realities of HTTP — retries, pagination, and error reporting. The wrapper is the contract between a flaky external service and a reasoning agent that needs predictable inputs to make good decisions.

Common Mistakes

Wrapping an API without a description that specifies when not to use it. Letting raw exceptions bubble up to the agent instead of returning structured error objects. Hardcoding pagination loops so the agent cannot skip pages or stop early. Ignoring the Retry-After header and using fixed delays that get you banned faster.