How an MCP tool actually works (part 2)
This is the second part in a short series on AI in Laravel, where I’m digging under the hood of MCP tools and looking at what the model is really doing when it decides to use one.
In the last post, I looked at how a tool gets exposed to the model: the config file tells the AI client which MCP server to start, the server publishes a list of tools, and the model sees a name, a description, and a schema. That means the real interface is not the PHP code behind the tool, but rather the metadata that the model reads.
This time, I wanted to write one myself, by hand, without letting the AI write it for me.
The tool is for Scout, a Statamic addon I’ve built that helps an AI agent plan and assemble pages. Scout already had a tool to check a page plan for mistakes, but it didn’t yet have a way for the agent to find out which page builder components exist before it starts planning. So the agent would guess, and the validator would correct it after the fact.
The new tool is called list-builder-components. Before writing any code, I answered four questions.
1. What should the model be told?
The description is the only part of a tool the model actually reads. It never sees the PHP that the tool runs, so the description has to say what the tool gives back and when to use it. In our case:
Lists the page builder components available to this app, including each component’s handle, title, and when to use or avoid it. Use this before starting any page building or validating work.
The last sentence here is really important, because it tells the agent where this tool fits in the sequence when it starts working, before it plans anything.
2. Does it need any inputs?
In this case, no inputs are needed. It just lists what’s there, so the schema is an empty array:
public function schema(JsonSchema $schema): array
{
return [];
}
3. What should come back?
This is about what gets returned from our PHP, and handed to the model to present back in response. Here, I want it to return a components object, keyed by each component’s handle. Every component has the same keys, and when a value is missing it should come back as null. That way the agent never has to wonder whether a key exists, it only has to check the value.
One PHP gotcha: an empty PHP array turns into [] in JSON, which is a list, not an object. So on a site with no components, the shape would be unintentionally different. Casting the empty case with (object) [] keeps it an object every time.
4. What if there’s no page builder?
For a site that doesn’t use one, this tool shouldn’t fail silently or error out. So instead, the tool returns the same shape with a notice:
{
"components": {},
"notice": "No page builder field is configured. Use a document-style plan, or set scout-assistant.page_builder_field."
}
When everything works, notice is null.
What happened when I ran it the first time
The first time I tested it after creating the tool wasn’t so smooth. As with most programming that’s where I learned the most.
The agent called a different tool. The app already had an older tool called list-components that did almost the same job, which was referenced by the project’s CLAUDE.md file; it was built by an agent earlier when I was developing Scout initially, but it was placed elsewhere and didn’t ship with it. So the agent used that one, even though mine was loaded.
The lesson is that when two tools overlap, the instructions in your prompt or project file can matter more than either tool’s description. Since I’m keeping my version, because I want it to ship with Scout going forward, I’ll remove the old one.
Then it crashed. I had called SiteContext::builderSets() as if it were a static method, meaning one you call on the class itself. It’s a regular method, so it needs an actual SiteContext object. The fix was dependency injection, to let Laravel pass one in through the constructor:
public function __construct(protected SiteContext $site) {}
Then the data was slightly wrong. pairs_with came back as entry IDs instead of component handles, which isn’t much help to an agent. Statamic stores relationships as IDs, so the tool has to convert them. In this case, this was a matter of finding the ids, and returning the slugs instead:
$slugsById = $catalog->mapWithKeys(fn ($e) => [$e->id() => $e->slug()]);
$pairs_with = $entry ?
collect($entry->get('pairs_with', []))
->map(fn ($id) => $slugsById[$id] ?? null)
->filter()->values()->all()
: null;
The pattern to remember
Here’s what I’m taking from this into every read-only tool I write:
- Mark it read-only
#[IsReadOnly], so the client knows it’s safe to run. - Write the description for the model, including when to call it.
- Only ask for the inputs you actually need.
- Return the same shape every time, with
nullfor missing values. - Use a notice for “nothing to show,” and save errors for real failures.
I’ll be using this pattern as I build out a Laravel Agent Starter Kit as a part of this series. Next up, I’m going deeper into Boost and laravel/mcp.
This is the second part of a short series I’m writing on AI in Laravel. Next up, I’m going deeper into Boost and laravel/mcp, to look at how a server is put together and how tools get registered, before I start building out the Laravel Agent Starter Kit. If you’d like each part in your inbox, along with a few things that don’t make it to the blog, sign up for the AI for Laravel series below.
Join my Email List
I write about how AI tools like MCP actually work, and practical AI for developers. I'll email you when a new part of the series is out.