How to write an AI agent's job description: role, tools, boundary

6 minute read · Written by the team that builds UtilitySpaces. More about UtilitySpaces.

To configure an AI agent, write three things down. A role: the job it does and what “done” looks like. A tool set: the named operations it may call in the apps you have connected. A boundary: which of those operations run unattended and which stop for a person. Model choice, schedule and channel come after, and matter less than any of the three.

We build UtilitySpaces, where an agent is literally a role, a set of tools and a boundary, so this is partly a description of the form you fill in. It is mostly a description of what goes wrong when one of the three parts is missing, because that is what we see when an agent disappoints somebody.

Why call it a job description?

Because the mistakes people make configuring an agent are the mistakes they make hiring. A vague role produces confident work on the wrong thing. Too much access produces an incident. No stated boundary produces a new hire who either asks about everything or nothing, and you cannot tell which you are going to get until it matters.

The analogy also sets the right expectation about length. A good job description is a page, not a paragraph and not a manual. If the role text is three sentences, the agent is guessing. If it is three thousand words, the agent is ignoring most of it and you cannot tell which part.

Part one: what goes in the role text?

Four things, in this order. What the job is, in one sentence. What a finished result looks like, concretely enough that a colleague could check it. What the agent should do when the input does not match the rule. And what it must not attempt even if asked.

The second of those is where most role text fails. “Triage incoming orders” is a title, not a definition of done. “For every new order, decide whether it can ship as placed, needs a stock check, or needs a human, and say which in one line with the reason” is a definition of done. A person reading the thread afterwards can see whether the agent did it.

The third is the part people forget because they wrote the rule while looking at the ordinary case. Write the exceptions as explicit instructions: when the address is incomplete, when the same customer has two open orders, when the item is out of stock. An agent told nothing about exceptions will improvise, and improvisation is the one behaviour you did not authorise.

Part two: which tools should the agent hold?

Exactly the operations the job needs, named one at a time. Not “access to the store”, but list orders, get an order, list products. If you cannot name the operation, the agent should not have it, and in UtilitySpaces it cannot call anything that is not on its list.

Tools come from connectors, each holding a scoped credential for one app. A connector exposes a fixed set of named operations, each marked as a read or a write. Picking the agent’s tool set is picking a subset of those, and the smaller the subset, the smaller the blast radius when the role text turns out to be ambiguous, or when something the agent read in a ticket tries to steer it.

The question to ask per tool is not “might this be useful?” It is “which sentence of the role text needs this?” If no sentence does, leave it out. You can add it next week with one decision. Taking it away after an incident costs considerably more.

Part three: where is the boundary?

The boundary is the list of actions that stop and wait for a person. The default worth starting from is simple: reads run unattended, writes stop. A wrong read is recoverable; a wrong write is already in someone else’s system. UtilitySpaces builds that split into the code rather than leaving it to the role text: reads run, and a connector write waits for an approval a person decides unless an admin has set that connection to run without asking.

On top of that default, the role text can tighten further. Some reads deserve a stop too: a bulk export, or reaching into a system the agent has not touched before. Some writes you will end up approving every single time, and after enough identical approvals the honest move is to narrow the rule so that one shape of write stops asking. The mechanics of that are in the piece on agent permissions and the approval gate.

A worked example: an order-triage agent

Here is the whole job description for an agent that looks at new store orders and decides what happens next. It is deliberately dull. Dull is what a good first agent looks like.

Notice what is absent: no tool that changes an order, no tool that emails anybody. The agent can be wrong all day and the worst outcome is a wrong line in a thread a person reads.

What are the common mistakes?

• Too many tools. The agent is given every operation the connector offers “in case”. Now the role text is the only thing between an ambiguous ticket and an unintended write, and role text is not a security control.
• A vague role. “Help with orders” gives the model a title and asks it to invent the job. It will, confidently, and differently each run.
• No boundary. Nothing says which actions stop. Either the agent asks about everything and people learn to click approve without reading, or it asks about nothing and you find out what it did from the log.
• Exceptions left to judgement. The rule covers the ordinary case and the agent is trusted to “use common sense” on the rest. The rest is where the incidents are.
• Two jobs in one agent. Triage orders and also draft supplier emails. Two jobs need two tool sets and two boundaries; combining them hands the wider set to both.

How do you test it with one real job?

Run the agent once, on real data, with every connection on “Ask a person first”, and read the whole thread. Not a synthetic example, because synthetic data never contains the exception that breaks the rule. One real run, then a second, then a week of them, with a person reading each one in the shared inbox where the output lands.

Three things to check per run. Did the agent call only the tools you expected, in an order that makes sense? Did every exception you wrote down get handled as written? And did it ever reach for something it did not have, which tells you either the job needs one more tool or the role text is inviting it to wander?

Keep a note of every run where you disagreed with the output and why. After ten such notes you will know whether the role text, the tool set or the boundary needs changing, and it is almost always the role text. The broader argument for starting with one boring, repeated job is in what to automate first with AI agents.

What a job description cannot fix

A good job description makes a wrong agent cheap. It does not make the agent right. The model will still misread an unusual input, and text the agent reads from a ticket or a web page can still try to steer it. The tool set and the boundary are the controls that hold when that happens; the role text is advice the model usually follows.

If you want to try the form rather than read about it, the demo workspace lasts exactly sixty minutes from creation, which is enough to write one role, pick three tools, run the agent once and see what it does. Start a demo workspace, or read the product overview first.