What is a tool call?
Connect a service to Claude, ChatGPT or Grok and you start to see new things in the chat: a small box saying the AI is using a tool, a request to allow it, a list of steps it took. Each of those is a tool call. Understanding them takes the mystery out of what your AI agent is doing with your messages, and shows you exactly where the safety checks sit.
In one sentence
A tool call is a single action an AI agent asks a connected service to carry out, such as "list my unread WhatsApp chats" or "send this reply in that conversation". The agent decides which tool to use and what to put in it, and the service does the work and reports back.
In more detail
A language model on its own can only write text. To do anything in the world, it needs tools: named actions that a service offers, each with a short description and a few inputs. When you connect Spaces to your AI app, the app learns the list of tools Spaces offers, such as reading conversations, replying in a chat, handing a chat to a person or scheduling a message.
When you ask the agent to do something, it reads the descriptions and picks the tool that fits. It fills in the inputs, such as which account and which conversation, and sends the request. The service carries it out, or refuses with a reason, and sends the result back. The agent reads the result and decides what to do next.
Most jobs take several tool calls in a row. Answering one customer message might mean reading the business notes, reading the recent messages in that chat, writing a reply and then sending it. You might see each step in your AI app as a small expandable box.
Many AI apps ask you before they use a tool, at least the first time, or for anything that changes something. That is the app checking with you. It is a useful moment to look at what the agent is about to do, especially when the tool sends a message or posts something public.
The service on the other end has its own checks too. It decides whether this agent is allowed to use that tool, whether the account has room under its limits, and whether sending is paused. The example below shows the tool calls behind one reply. Names and details are examples.
An example
| Step | What the agent does |
|---|---|
| You ask | "Answer any new WhatsApp messages for the bike shop." |
| Tool call 1 | Reads the business brief, to load opening hours, prices and hand-over rules. |
| Tool call 2 | Lists unread WhatsApp chats. One new message, from Joe. |
| Tool call 3 | Reads the recent messages in Joe's chat. Joe asks if a puncture can be fixed today. |
| Tool call 4 | Replies in Joe's chat: "Hi Joe, yes, bring it in before 4pm and it will be ready in about an hour. Puncture repairs are £12." |
| Result | Spaces confirms the reply was accepted and paced. The agent tells you: "Answered Joe about a puncture repair." |
Reading tools and writing tools
| Kind of tool | Examples | What to watch |
|---|---|---|
| Reading | List chats, read messages, read the business brief, check account limits | Low risk; reading your own conversations is paced so it puts little pressure on the platforms |
| Organising | Tag a chat, give it an owner, star or archive it, mark it unread | Sends nothing to the customer |
| Handing over | Hand a chat to a person, hand it back | Stops the agent replying in that chat until it is handed back |
| Writing | Reply in a chat, start a new chat, send an email, schedule a message | Reaches a customer, so it is paced, counted and can be held as a draft |
| Public | Post, comment, react | Everyone can see it, so hold these for approval |
A simple rule: be relaxed about reading and organising tools, and pay attention to writing and public ones.
When a tool call is refused
A refusal is not a breakdown. It is a safety check doing its job, and the agent gets a plain reason it can act on. Common ones are:
- Not allowed: this agent does not have permission for that kind of action, such as posting.
- Paused: sending has been paused, for one agent or for everything.
- Wait first: the account or the agent's share has reached a limit for now, with a time to try again.
- Needs attention: the account needs signing in again before it can be used.
A good agent tells you what happened in plain words rather than trying another route around the check.
What if…
| What if… | What happens |
|---|---|
| The agent picks the wrong tool? | Usually the result tells it so, and it tries the right one. If it keeps choosing badly, add a line to its notes, such as "to answer a customer, reply in their existing chat; never start a new one". |
| The agent sends the right reply to the wrong chat? | This is why it helps to read the inputs of writing tools while you are getting started. Ask the agent to name the customer before each send, so a mismatch stands out. |
| Two agents call the same tool at once? | Both calls go through the same account limits and pacing, so they queue rather than flood the account. Give each agent its own access so you can see which one did what. |
| The connection drops halfway through? | The agent can try again. Because each send carries an idempotency key, a repeat of the same send does not reach the customer twice. |
Reading the tool calls in your AI app
- Open the small box the app shows for each tool call. It usually lists the tool's name and the inputs.
- Check the account and the conversation are the ones you expected.
- For a reply, read the text before you allow it, if the app asks you.
- Read the result. It tells you whether the action went through, was held as a draft or was refused.
- If something looks wrong, stop the agent and ask it to explain what it was trying to do.
Common mistakes
- Clicking "always allow" for every tool on day one. Allow reading freely, and look at writing tools until you trust the agent.
- Giving one agent every permission. An agent that only answers messages does not need to post or connect new accounts.
- Assuming a refused call is a bug. Read the reason; it is usually a limit, a pause or a permission.
- Asking the agent to retry a send over and over. Writes are protected against sending twice, and the limits still apply.
Why it matters for your business
- Every action your agent takes on your accounts is a tool call you can see, which makes it easier to trust and to check.
- Knowing which tools write to customers tells you where to slow down and approve.
- Refusals tell you a limit, a pause or a permission is working, rather than that something is broken.
- Giving each agent only the tools it needs keeps a mistake small.
- Reading tool results helps you spot a misunderstanding before it reaches a customer.
How Spaces handles it
Spaces offers its tools through one MCP server at https://api.spacesos.com/mcp, with a URL per channel if you want an agent to see only one. The tools cover conversations, messages, hand-over, tags and owners, scheduled messages, routines, account limits and more, across WhatsApp, Instagram, LinkedIn, Messenger, X and email.
Every write tool is checked before anything is sent. Spaces looks at the agent's own permissions, the account limits, the agent's share of the day and whether sending is paused. Every send needs an idempotency key, so a retried call is never sent twice. Every refusal comes back with a short code, a plain reason and a link to a page explaining what to do.
If you want to see every reply before it goes, ask your AI agent to hold replies as drafts, and nothing goes out until you approve it. Public posts and comments can be held the same way.
In short
A tool call is one action your AI agent asks a service to carry out. Most jobs are a short chain of them: read, decide, write.
Be relaxed about reading tools, look closely at writing ones, and treat a refusal as a safety check doing its job.
FAQ
Why does my AI app ask me to allow a tool?
Many AI apps check with you before a tool runs, at least the first time or for anything that changes something. It is a chance to see what the agent is about to do before it happens.
Is a tool call the same as an API call?
They are closely related. A tool call is the agent asking for an action in plain terms, and the service usually carries it out with an API call behind the scenes. You do not need to deal with the API yourself.
How many tool calls does one reply take?
Usually a few: reading the notes, reading the chat, then sending the reply. A catch-up across many chats can take dozens. Reading is paced, and sending is counted against the account limits.
What happens if a tool call is refused?
Nothing is sent, and the agent gets a plain reason, such as a limit, a pause or a missing permission. A good agent tells you, and waits or asks you rather than looking for a way around it.
Can my agent use tools I did not give it?
No. It can only use the tools the connected service offers, and Spaces also checks the agent's own permissions on every call. If an agent is not allowed to post, a post is refused.
Can I see what tool calls my agent made?
In a chat app, each tool call usually shows as a small box you can open. Always-on agents normally keep a log. You can also ask the agent to summarise what it did.
Could a retried tool call send the same message twice?
Not through Spaces. Every send carries an idempotency key, so if the agent repeats the same call, the customer still gets one message.