Giving agents custom tools and integrations · Agentic Engineering: the hands-on course

An agent is only as capable as the tools it can call. Start with a script in the repo, graduate to a real tool integration when you need one, and design every tool for a reader that isn't you.

Out of the box, a coding agent can read files, edit them and run shell commands. That covers a lot. But it can’t see your error tracker, your feature flags or the staging logs unless you give it a way in.

Custom tools are that way in. The skill is not building them: it’s knowing which kind to build, and designing them so the agent uses them well.

The integration ladder

I always start at the bottom rung and climb only when the one below stops working. Each rung up costs more to build and maintain.

Climb only as high as you need. Most teams get far with rungs 1 and 2.

A script in the repo is already a tool: the agent can read it, run it and see the output. Rung 4 means a proper integration, often through an open protocol such as the Model Context Protocol (MCP), so any compatible agent can discover and call it with typed inputs.

Design for a reader that isn’t you

The agent decides whether and how to call your tool from its name, its description and its error messages. That’s the whole interface. Write it like documentation for a smart new hire with no context.

✕ Tool the agent misuses

–Name: 'query'
–Description: 'Runs a query'
–Returns 5,000 rows of raw JSON
–Error: 'failed'
–Can write to any table

✓ Tool the agent uses well

+Name: 'search_recent_errors'
+Says when to use it and when not to
+Returns the top 20, summarised, with a way to page
+Error explains what was wrong and how to fix the call
+Read-only, scoped to one service

search_recent_errors
Find recent errors from the error tracker for ONE service.
Use it when investigating a bug report or a failing deploy.
Don't use it for metrics or performance questions.

Inputs:
- service (required): name as it appears in the services list
- since (optional): e.g. "2h" or "3d". Default "24h".

Returns up to 20 grouped errors: message, count, first/last seen,
one sample stack trace. Ask for the next page with the cursor.

Play: which rung?

🎮 How would you give the agent this ability?

1 / 8 · Score: 0

Before you move on

✅ Key takeaways

0 / 4 completed

I climb the integration ladder only as high as I need.
Every tool has a specific name and a description that says when not to use it.
Tool outputs are short and errors tell the agent how to fix the call.
New tools start read-only; write actions come one at a time, behind approval.