• Practice
  • About 16 min
  • 5 practice questions

Tools and APIs: how an agent reaches other software

Read a simple API request and JSON response, explain how a language model is given tool descriptions and asks for a tool call that the software runs, sort tools into read-only and write, and keep keys out of prompts.

If something looks wrong, please tell us.

By the end of this lesson you can

  • Explain an API request and response, and read a small JSON example.
  • Describe how a model asks for a tool call and who actually runs it.
  • Separate read-only tools from write tools, and say where keys and passwords belong.

An agent is only as useful as its tools, and almost every tool reaches other software through an API. Understanding requests, responses and tool calls shows what an agent can do - and where the risks lie.

What an API is

An API (application programming interface) is an agreed way for one program to ask another for data or an action. Think of a post-office counter: you fill in a standard form (the request), hand it over, and receive a receipt in a standard format (the response). Each service an API offers sits at an endpoint, an address such as /notices or /students/1042/results. A request names the endpoint, a method - GET to read, POST to create, and others such as PUT to change or DELETE to remove - and any details needed. The response carries a status code and the data. Common codes: 200 means success, 404 means the item was not found, and 401 means the caller is not authorised, for example because its key is missing or wrong.

An API call

  • Request
    • The endpoint, such as /notices
    • A method: GET to read, POST to create, PUT to change, DELETE to remove
    • Any details needed
  • Response
    • A status code: 200 success, 404 not found, 401 not authorised
    • The data

Worked example 1: reading a JSON response

Suppose a coaching institute's own booking system has an endpoint /tests/upcoming. A GET request to it might return the response below, written in JSON (JavaScript Object Notation), a plain-text format of names and values.

{"tests": [{"id": 31, "subject": "Reasoning", "date": "2026-11-02", "seats": 12}, {"id": 32, "subject": "English", "date": "2026-11-09", "seats": 0}]}

— Illustrative response from a fictional booking system

How to read it: curly braces hold an object made of name-value pairs; square brackets hold a list; text is in double quotes and numbers are not. So the list under "tests" contains two tests. Test 31 is Reasoning with 12 seats left; test 32 is English with 0 seats left, so it is full. Software reads this reliably because the format is fixed, unlike a web page laid out for human eyes.

How a model uses a tool

A language model on its own only produces text. It cannot open a website or press a button. Tool use works like this:

  1. The developer gives the model tool descriptions: each tool's name, what it does and what inputs it needs - for example getUpcomingTests (no inputs) and bookSeat (a test ID and a student ID).
  2. A user states a goal: 'Book Ravi a seat in the next Reasoning test.'
  3. The model does not call anything itself. It replies with a structured tool call request: use getUpcomingTests.
  4. The surrounding software checks that the call is allowed, runs the real API request and passes the result back to the model.
  5. The model reads the result and either asks for another tool - bookSeat with test 31 and Ravi's ID - or writes its final answer.

The central idea: the model proposes, the software executes. That gap is where every safety check lives - the software can refuse a call, ask a person first, or limit how often a tool runs. Different companies call this 'function calling' or 'tool use', and shared conventions such as the Model Context Protocol describe how tools are offered to models; the principle is the same everywhere.

How a model uses a tool

  1. Tool descriptions The developer gives each tool's name, purpose and inputs.
  2. A user states a goal
  3. The model requests a tool call It does not call anything itself.
  4. The software checks and runs it It runs the real API request and passes the result back.
  5. The model reads the result It asks for another tool or writes its final answer.

Read-only and write tools

Two kinds of tools
KindWhat it doesExamplesRisk
Read-onlyLooks at data without changing anythingSearch notices, read a file, list upcoming testsLower: the worst case is a wrong reading or exposed data
WriteCreates, changes, sends or deletes somethingBook a seat, send an email, make a payment, delete a recordHigher: effects reach the real world and may be impossible to undo

Worked example 2: deciding what runs freely

In Ravi's booking, getUpcomingTests is read-only: running it twice by mistake harms nobody, so the agent may call it freely. bookSeat is a write tool: it changes the institute's records and takes a seat from someone else. A careful design lets the agent search as needed but shows the planned booking - test, date, student - to a staff member, who confirms before bookSeat runs. Had the model picked test 32, the response would show 0 seats and the booking would be refused: real results, not the model's intentions, decide.

Keys stay with the software

Most APIs ask the caller to prove who it is, usually with an API key or token - a long secret string that works like a password. The software stores the key in protected configuration on the server and attaches it to each request itself. The key must never be written into a prompt, a tool description or a chat: anything the model sees could be repeated in its output, saved in logs or leaked if the model is tricked. The model should see only the tool's name and its result, never the secret that opened the door. The same rule applies to you: never paste passwords, OTPs, Aadhaar numbers or confidential office files into any AI tool.

The model proposes a tool call; the software checks it, runs it with keys the model never sees, and returns the result.

Key takeaways: an API is a request to an endpoint that returns a status code and data, often as JSON. A model is told which tools exist and asks for calls; the software decides whether to run them. Read-only tools can run freely; write tools need limits and often a person's confirmation. Keys live with the software, never in a prompt.

Check your understanding

  1. 1. In an API, what is an endpoint?

    1. The last step of an agent's plan
    2. A specific address at which the API offers one service, such as /tests/upcoming
    3. The password used to sign in to a website
    4. The moment the model stops generating text
    Show answer

    Answer: B. Each service an API offers has its own address, called an endpoint. Requests are sent to an endpoint with a method such as GET or POST.

  2. 2. A results API returns {"student": "Meena", "marks": [42, 38, 45], "passed": true}. What is the sum of the values in the marks list?

    1. 115
    2. 3
    3. 125
    4. 45
    Show answer

    Answer: C. The square brackets hold a list of three numbers: 42 + 38 + 45 = 125. The count of values is not their sum, and 45 is just the largest value.

  3. 3. When an agent 'uses a tool', who actually runs the API request?

    1. The surrounding software, after the model asks for the call in a structured request
    2. The language model, which connects to other servers by itself
    3. The user, who must type every request by hand
    4. Nobody - the model only imagines the result
    Show answer

    Answer: A. The model only produces a tool call request. The software checks it, runs the real request and hands back the result - which is why safety checks can sit between the two.

  4. 4. Which of these is a write tool?

    1. searchNotices - finds notices containing a word
    2. readFile - returns a file's text
    3. sendEmail - sends a message to a parent
    4. listTests - returns the upcoming test list
    Show answer

    Answer: C. Sending an email changes the world outside the system and cannot be undone. The others only look at data without changing anything.

  5. 5. A developer's agent must call a results API that needs a secret key. Where should the key be kept?

    1. In the system prompt, so the model can use it
    2. In the tool description, so the model knows it
    3. In the chat, typed in by the user each time
    4. In the software's protected configuration, attached to requests by the software and never shown to the model
    Show answer

    Answer: D. Anything the model sees could be repeated, logged or leaked. The software holds the key and adds it to requests; the model needs only the tool name and the result.

Privacy · Terms · Refunds · Delivery