Agent engineering: MCP, subagents and agentic systems · Chapter 2 of 14 · AI Engineering · new chapter every Sunday morning
By the end of this chapter: Write tool schemas a model uses correctly on the first attempt.
The problem
Say you are a senior backend engineer at a fintech startup. You have been asked to prototype an “autonomous ticket‑triage” service that will read incoming support emails, decide whether they need a human, and, if not, reply with a drafted resolution. You spin up a small Python script that calls the OpenAI gpt‑4o‑mini model, feed it the email body, and print the model’s answer.
When you run the script against a handful of real tickets you see two symptoms:
- The script prints the same generic apology for every ticket, never reaching the “human‑escalate” branch you coded.
- After a few minutes the process is killed by the OS with
MemoryError.
This costs you several hours of debugging time, and you start to question whether the gpt‑4o‑mini model is the right tool for the job. You also wonder if there's a way to define the tools and their interactions more explicitly, to avoid similar issues in the future.
Before you start
To follow along with this chapter, you should have:
- Python 3.9 or later installed on your system
- The
openailibrary installed (pip install openai) - A basic understanding of the
gpt‑4o‑minimodel and its limitations (covered in Chapter 1) - A working knowledge of Python and its ecosystem
You can verify that your setup is working by running the following command:
import openai
print(openai.__version__)
This should print the version of the openai library you have installed.
Defining tool contracts
To write tool schemas that a model uses correctly, we need to define the tools and their interactions more explicitly. This involves creating a contract that specifies the input and output formats, as well as any constraints or assumptions that the tool makes.
In the case of the gpt‑4o‑mini model, we need to define a schema that specifies the input format for the email body, as well as the expected output format for the model's answer. We also need to consider any constraints or assumptions that the model makes, such as the maximum length of the input text or the expected format of the output.
Tool schema basics
A tool schema is a JSON object that defines the input and output formats for a tool, as well as any constraints or assumptions that the tool makes. The schema should include the following elements:
-
name: a unique name for the tool -
input: a description of the input format, including any required fields or constraints -
output: a description of the output format, including any required fields or constraints -
constraints: a list of any constraints or assumptions that the tool makes
For example, a tool schema for the gpt‑4o‑mini model might look like this:
{
"name": "gpt-4o-mini",
"input": {
"type": "string",
"max_length": 2048
},
"output": {
"type": "string",
"max_length": 2048
},
"constraints": [
"input text must be in English",
"output text must be in English"
]
}
Build it
To write a tool schema for the gpt‑4o‑mini model, follow these steps:
- Create a new JSON file called
tool_schema.json - Add the following code to the file:
{
"name": "gpt-4o-mini",
"input": {
"type": "string",
"max_length": 2048
},
"output": {
"type": "string",
"max_length": 2048
},
"constraints": [
"input text must be in English",
"output text must be in English"
]
}
- Save the file and verify that it is valid JSON by running the following command:
jq . tool_schema.json
This should print the contents of the file in a pretty-printed format.
When this breaks
There are several ways that a tool schema can break, including:
- Invalid JSON syntax
- Missing or incorrect fields
- Constraints that are not met
If the tool schema is invalid, the gpt‑4o‑mini model may not work as expected, or may produce incorrect results. To debug a broken tool schema, follow these steps:
- Verify that the JSON syntax is valid by running the
jqcommand - Check that all required fields are present and correct
- Verify that the constraints are met by checking the input and output formats
What it costs
Defining a tool schema for the gpt‑4o‑mini model has several costs, including:
- Time and effort required to create and validate the schema
- Potential limitations on the flexibility of the model
- Risk of errors or inconsistencies in the schema
However, the benefits of defining a tool schema include:
- Improved accuracy and reliability of the model
- Reduced risk of errors or inconsistencies
- Easier debugging and maintenance of the model
In the interview
In an interview, you may be asked to explain the concept of a tool schema and how it is used in agent engineering. A weak answer might sound like this:
"I think a tool schema is like a blueprint for a tool, it defines how the tool works and what it does."
A stronger answer might sound like this:
"A tool schema is a formal definition of the input and output formats for a tool, as well as any constraints or assumptions that the tool makes. It's used to ensure that the tool is used correctly and consistently, and to reduce the risk of errors or inconsistencies. For example, in the case of the gpt‑4o‑mini model, a tool schema would define the input format for the email body and the expected output format for the model's answer."
A follow-up question might be:
"Can you give an example of how you would define a tool schema for a specific tool, such as the gpt‑4o‑mini model?"
Your tasks
- Create a tool schema for a different tool, such as a natural language processing library or a computer vision model.
- Write a Python script that uses the
gpt‑4o‑minimodel to classify a set of example emails, using the tool schema defined in this chapter. - Debug a broken tool schema by identifying and fixing errors in the JSON syntax or constraints.
Note: The tasks are designed to be completed independently, and the solutions will not be provided. The goal is to provide a starting point for further exploration and learning.
Your tasks this week
Do the exercises above before the next chapter. Reading a tutorial and doing
one are different activities and only one of them changes what you can build.
Stuck on any of them? Say so — describe what you tried and what happened:
tell me where you got stuck. I read every one, and the questions
that come back more than twice get answered in the next chapter.
Agent engineering: MCP, subagents and agentic systems
Chapter 2 of 14. New chapter every Sunday morning.
Next: The context window as a budget.
· The full syllabus and every chapter so far
· Subscribers also get the condensed notes for this chapter, the running
recap of everything the series has covered, and the extended guidance:
subscribe
Written by Amit Chakraborty — founding engineer and senior architect: React Native, AI and RAG systems, production architecture. Portfolio · LinkedIn · GitHub.
Need this built, reviewed or taught to your team? Get in touch or email [email protected]. Available for senior and founding engineering roles, consulting and training, remote worldwide.
Top comments (0)