AI Agent Prompt to Call an API: How to Write One

When people search for "ai agent prompt to call api," they usually want one of two things: a prompt template that gets an LLM to reliably invoke an external API through tool/function calling, or a working example showing the full loop — prompt, tool definition, API call, and response handling. This article covers both.

The short answer: you don't write a single magic sentence that makes an agent "call an API." You define a tool schema (name, description, parameters), give the model a system prompt that explains when and how to use it, and let the model's tool-calling mechanism emit a structured request that your code executes. The prompt's job is to make the model choose the right tool at the right time with the right arguments — the actual HTTP request is handled by your application code, not the model itself.

Why "just ask the model to call the API" doesn't work

An LLM has no network access by default. It can't send an HTTP request on its own. What it can do, if you're using a model that supports tool use (also called function calling), is output a structured object like:

{
  "tool": "get_weather",
  "arguments": { "city": "Lisbon" }
}

Your application then reads that object, makes the actual API call, and feeds the result back into the conversation. The "prompt to call an API" is really two things working together:

1. The tool schema — a machine-readable description of what the API does and what parameters it needs.
2. The system prompt — natural-language instructions telling the model when to use that tool, how to interpret ambiguous requests, and what to do with the result.

Get either one wrong and the agent either never calls the tool, calls it with malformed arguments, or calls it when it shouldn't.

Anatomy of a good tool-calling prompt

A reliable setup has four parts:

1. A precise tool description

The model decides whether to call a tool based almost entirely on the description field, not your system prompt. Be specific about inputs, outputs, and edge cases:

{
  "name": "get_order_status",
  "description": "Look up the current status of a customer order by order ID. Returns status, estimated delivery date, and tracking number. Use this whenever the user asks about an existing order, refund status, or delivery timing.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string", "description": "The order ID, e.g. ORD-48213" }
    },
    "required": ["order_id"]
  }
}

Vague descriptions like "gets order info" cause models to skip the tool or guess arguments instead of asking for missing ones.

2. A system prompt that sets behavior, not mechanics

The system prompt shouldn't re-explain the schema — the model already sees that. It should cover judgment calls:

You are a support assistant. When a user asks about an order, always
call get_order_status instead of guessing. If you don't have the order ID,
ask for it before calling the tool. Never make up tracking numbers or
delivery dates — only report what the tool returns.

3. Few-shot examples for ambiguous cases

If your tool has parameters the model tends to misformat (dates, enums, IDs), show one or two examples in the prompt or as prior turns. This matters more than people expect — a single well-placed example often fixes a recurring argument-formatting bug faster than rewriting the description.

4. Explicit handling of the tool result

Tell the model what to do once it gets data back — summarize it, ask a follow-up, or chain into another tool call. Without this, agents sometimes just repeat the raw JSON back to the user.

A working example

Here's a minimal loop using tool calling against a Claude-compatible API. If you're routing requests through SubToAPI, the request shape is the same Messages format you'd use directly with Claude, with tools defined per the docs/tools reference:

const response = await fetch("https://api.subtoapi.app/v1/messages", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SUBTOAPI_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "claude-sonnet-4",
    max_tokens: 1024,
    system: "You are a support assistant. Call get_order_status whenever the user asks about an order. Never invent order data.",
    tools: [
      {
        name: "get_order_status",
        description: "Look up order status by order ID. Returns status, ETA, and tracking number.",
        input_schema: {
          type: "object",
          properties: { order_id: { type: "string" } },
          required: ["order_id"]
        }
      }
    ],
    messages: [
      { role: "user", content: "Where's my order ORD-48213?" }
    ]
  })
});

const data = await response.json();
// data.content will include a tool_use block with name and input

Your code then executes the real API call (hitting your order system), and sends the result back as a tool_result block in the next request so the model can turn it into a natural-language reply. Full request/response shapes are in docs/messages.

Common failure modes

• Tool never gets called. Usually a weak description, or the system prompt burying the instruction under unrelated content. Keep tool-triggering instructions near the top.
• Wrong arguments. Add a description to each parameter, not just the tool. Models rely on per-field hints for formatting.
• Model hallucinates a result instead of calling the tool. Add an explicit rule: "Never answer questions about X without calling the tool first."
• Infinite tool-calling loops. Cap the number of tool round-trips in your application logic, not the prompt — don't rely on the model to self-limit.
• Streaming breaks mid tool-call. If you're streaming responses, buffer tool_use blocks until they're complete before executing them; partial JSON will fail to parse. See docs/streaming for the event sequence.

Testing your prompt

Treat the prompt-plus-schema pair as code: write a small test set of user messages covering the happy path, missing parameters, and irrelevant questions that shouldn't trigger the tool at all. Run them against your actual API key — behavior varies more than expected between model versions, so a prompt that works today should be re-verified after a model upgrade. If you're getting started, the quickstart walks through issuing a sub_live_ key and making your first tool-enabled request end to end. Plans and rate limits are on pricing, and you can try the full flow from a free trial at signup.

questions

Do I need a special prompt format to make an agent call an API? No. You need a tool/function schema plus a system prompt that tells the model when to use it. The model outputs structured arguments; your code performs the actual HTTP call.

Can the model call the API directly without my code in the loop? No standard LLM API does this. The model emits a tool-call object; your application executes the request and returns the result in the next turn.

Why does my agent call the tool with missing or malformed arguments? Usually the parameter descriptions are too vague. Add explicit descriptions and formatting examples for each field, and mark required fields in the schema.