AI agent tools: turn a proposal into a controlled action
An AI agent tool is an application-defined operation the system can request, such as looking up a record or calculating a value. A tool needs a clear purpose, expected arguments, access limits and a result format. The model proposes a call; the application validates and executes the actual operation.
This guide is for anyone designing or reviewing a tool-using system. We will use one narrow operation, lookup_lesson, to show how a readable description becomes a reliable execution contract. Add broader capabilities only after their purpose and checks are clear.
Key ideas
- A clear tool does one understandable job.
- Validate arguments and authorisation before execution.
- Return status and relevant evidence, not an ambiguous wall of text.
- A standard connection protocol does not grant permission by itself.
Describe the job and its boundaries
A catalogue lookup should explain which catalogue it searches, the input key it accepts and what an absent record looks like. Naming the tool 'do_everything' makes its contract hard to inspect. Write the description from the caller's perspective: when should this operation be used, what does it return and what does it never change? The same clarity helps people debug calls and helps a model distinguish a lookup from a publication or enrolment action.
Use a schema and enforce it
For the teaching lookup, require an object with a single string key and reject unexpected fields. A schema describes that expectation. The execution function still needs to enforce input validity and authorised access. Treat the proposed call as untrusted input, even when the model usually produces correct structures. A syntactically valid request can still ask for a record outside the allowed scope, so format checks and access checks are separate responsibilities.
Make the result meaningful
Return whether the operation succeeded, whether the record exists and the evidence needed for the next decision. Distinguish an unavailable service from a successful search with no match. Otherwise the system may respond to a connection failure as if the requested lesson does not exist. For a catalogue record, a title, identifier and prerequisite can be enough. Avoid sending the entire database when one record answers the current question.
What MCP changes
Model Context Protocol defines a way for applications to connect with servers that expose capabilities such as tools and resources. Its architecture separates the host application, protocol clients and servers. This can reduce connection-specific work, but the host still has to decide what access is permitted and how results enter the task. Adding an MCP server does not make every exposed action appropriate for every user or turn its content into trusted instructions.
Test the boundary as well as the happy path
Test a known lesson, a missing key, a malformed argument, an unregistered tool and a request outside the permitted catalogue. Check that rejected calls never execute and that error statuses remain visible. If an operation changes external data, examine retry behaviour and how an already completed change is recognised. Start with the read-only classroom lookup, preserve its trace and widen the tool set only when another operation has a defined need and acceptance check.
In everyday language
A tool is a service counter with a specific form. The form explains what you can request, the counter checks whether you may request it and the receipt says what actually happened. Giving the counter a standard connector does not remove those checks.
Try it yourself
Write a lookup_lesson contract: purpose, input fields, permitted catalogue, success result, empty result and error result. Add one invalid argument and one unauthorised request, with the rejection point for each.
Expected result
A tool specification that makes successful lookup, no match and operational failure distinct, and rejects disallowed calls before execution.
Check your answer: Does a valid JSON argument prove the requested action is authorised?
No. It proves only that the input has an acceptable structure. Access and task permissions require their own checks.
Questions
Is a tool the same as a prompt?
A prompt gives instructions or context to a model. A tool is an operation implemented by the surrounding application or connected service. The model may propose a call based on its instructions, but actual execution, access checks and result handling belong to the application's tool boundary.
Should I expose every API as an agent tool?
Start from the tasks the system must perform. A small number of clear operations can be easier to use and review than a large collection of overlapping endpoints. Test the tool set on representative tasks and add another operation when its role and boundaries are distinct.
Write the tool contract, enforce it at execution and inspect the receipt. That turns a proposed action into work you can verify.
Sources and further reading
- Anthropic — Writing effective tools for agents ↗Sources checked:
- Model Context Protocol — Architecture overview ↗Sources checked:
- OpenAI — Safety in building agents ↗Sources checked: