DEV Community

Cover image for Agent engineering: MCP, subagents and agentic systems · 2. Tool definitions as a contract
Amit chakraborty
Amit chakraborty

Posted on Originally published at amitchakraborty.dev

Agent engineering: MCP, subagents and agentic systems · 2. Tool definitions as a contract

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 openai library installed (pip install openai)
  • A basic understanding of the gpt‑4o‑mini model 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__)
Enter fullscreen mode Exit fullscreen mode

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"
  ]
}
Enter fullscreen mode Exit fullscreen mode

Build it

To write a tool schema for the gpt‑4o‑mini model, follow these steps:

  1. Create a new JSON file called tool_schema.json
  2. 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"
  ]
}
Enter fullscreen mode Exit fullscreen mode
  1. Save the file and verify that it is valid JSON by running the following command:
jq . tool_schema.json
Enter fullscreen mode Exit fullscreen mode

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:

  1. Verify that the JSON syntax is valid by running the jq command
  2. Check that all required fields are present and correct
  3. 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

  1. Create a tool schema for a different tool, such as a natural language processing library or a computer vision model.
  2. Write a Python script that uses the gpt‑4o‑mini model to classify a set of example emails, using the tool schema defined in this chapter.
  3. 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)