Engineer Tools, Identity, and Protocols

Koko: Here is the single idea that separates agents that work in production from agents that work in demos: the model thinks, the tool acts. Everything the agent actually does to the world — moves money, updates a record, sends a message — happens through a tool. So if the tool is sloppy, none of the clever reasoning upstream matters. That is what this lesson is about.

Max: And when you say sloppy, you mean like a function someone just wired up quickly to get the prototype moving?

Koko: Exactly that. The trap is treating a tool like a quick helper function. The instinct a strong builder has is treating every tool like a public API that a team you will never meet has to call correctly, under pressure, at two a m, from inside a retry loop. That is the bar.

Max: That is a pretty high bar for something that might just be, like, a database lookup.

Koko: Even the lookup. Because the agent is going to reason on whatever the tool returns, and if that return is a giant blob with fifty fields, ambiguous sourcing, and no indication of what is authoritative — the agent's downstream claims are already shaky. Every tool, no exceptions, has to carry a contract.

Max: Okay, so walk me through what that contract actually looks like.

Koko: Five things, baseline. A strict input and output schema — the tool declares exactly what it accepts and returns, and rejects anything off-spec rather than guessing. A concise result — not the whole database row, just the fields the agent actually needs, with their source. That second part is provenance: every value tells you where it came from so any downstream claim can be traced back.

Max: So provenance is basically the audit trail built into the response itself.

Koko: Exactly. And then two more: the tool validates its own inputs and refuses malformed or out-of-range calls rather than trusting the caller to have been careful. And failures return something the agent can actually reason about — not error five hundred, but something like amount exceeds the policy cap of X. Actionable errors.

Max: So the tool is responsible for its own quality. It does not just pass the mess downstream.

Koko: Right. Think of it like a labeled circuit breaker. One clear job, the right amperage, and it trips safely when something is wrong. A bad tool is a bare wire left in the panel. It works right up until it doesn't, and then it takes the whole building.

Max: I like that. Okay, so that is the baseline. What about tools that actually do something consequential — like moving money?

Koko: That is where the contract gets a longer checklist, and every item on it earns its place. Let's use a concrete example. Call it Northwind's issue refund tool — an agent resolving a customer dispute and issuing a refund.

Max: Classic use case. What does a well-designed version of that look like?

Koko: Start with idempotency. The tool is atomic — same request id, one movement of money, full stop. A network timeout happens, the caller retries, and the refund still only executes once.

Max: Okay, but honestly — is that really necessary? If we are careful not to call it twice, do we need idempotency built in?

Koko: You do not control the network. That is the whole point. Timeouts happen. The framework retries. And without idempotency, one retry is a double refund. This is not a nice-to-have. On a money-moving tool, idempotency is the floor.

Max: So over-engineering is the wrong frame entirely — it is actually just correct engineering for the environment the tool lives in.

Koko: Exactly. And idempotency is what makes the next property safe: a bounded retry policy. Because when retrying cannot cause harm, you can retry confidently. You also get a real confirmation id back — not the word ok, an actual id you can reconcile against the ledger.

Max: That confirmation id is basically what the controller asks for when she wants to know whether the payment actually happened.

Koko: In those exact words, yes. Now add a few more properties. The tool is permissioned to a policy cap — it refuses to issue above the entitlement. It has a dry-run mode, so you can ask it what it would do before it does it, which is invaluable for evaluation and for a preview-before-commit approval step. And above a threshold, it requires human approval — enforced by the tool, not by a note in the prompt.

Max: That last one is interesting. Why does it matter whether approval lives in the tool versus the prompt?

Koko: Because a prompt can be overridden. It can be forgotten in a different version. It can be reasoned around. A control that lives in the tool is structural. Nobody can talk the tool out of it.

Max: So approval-in-the-tool is a preventive control, not just a detective one.

Koko: That is exactly the language to use with a client's internal audit team. And the tool is reversible — there is a defined path to void a refund. That is the full picture. Now contrast that with a broad update account tool that also edits contact details and credit limits, holds standing admin credentials just in case, retries blindly on timeout, and returns a chatty blob. Same feature — resolve a dispute — wildly different blast radius.

Max: And in our world — working with finance and operations teams at portfolio companies — that blast radius conversation lands immediately. A duplicate disbursement to a supplier is exactly what shows up in an auditor's management letter.

Koko: Right. So when you sit with a shared-services team and walk through a procure-to-pay agent that posts vendor payments, you can speak their language directly. The concise result with provenance is the audit trail. The confirmation id is what reconciliation ties to. The policy cap enforced in the tool is a preventive control the auditor can point to. And idempotency is the single control standing between a retried API call and a duplicate disbursement.

Max: That reframe — tool contract as control narrative — is something you can put straight in front of internal audit.

Koko: And it changes the conversation from a technical spec review to a risk management discussion, which is where those decisions actually get made. So: tools are products. They have contracts. The contract is engineered, not assumed. And for anything consequential, the safety properties are built into the tool itself — not hoped for in the prompt.

Koko: So here is the pivot. In the last module we talked about the contract — what a tool is allowed to do. Now we are going one layer deeper: identity. Because the contract governs what an action does, but identity governs what the agent can even reach in the first place.

Max: Okay, so the contract is the rules of the road, but identity is whether you even have a key to the car.

Koko: Exactly. And the load-bearing sentence of this whole module is this: excess agency plus excess privilege is how a small bug becomes a big incident. Write that one down.

Max: Excess agency plus excess privilege. So it is not just one thing going wrong — it is the combination.

Koko: Right. A confused or even compromised agent can only ever do what its credential permits. The credential — not the prompt — is the real boundary. The permission set is the actual fence. The prompt is just a sign that says please stay on the path.

Max: That is a meaningful distinction. Because a sign can be ignored. A fence cannot.

Koko: And that is the whole game. So think about it this way: least privilege is a hotel key card, not the master key. Your guest card opens your room and maybe the gym. It expires at checkout. Every door it touches gets logged.

Max: Right, and the master key opens everything and remembers nothing.

Koko: Which is exactly why you never hand the master key to a temp on their first day. And the rule is: treat every agent as the temp on their first day. Every single time.

Max: So the instinct is to scope down as tight as possible.

Koko: Scope credentials per tool and per action, not just per agent. For every capability, you ask one question: what is the smallest grant that still does the job? Read-only where reads suffice. Scoped to the one customer or record in play. No standing write access held just in case.

Max: Just in case is the killer phrase, isn't it. That is where things get padded out.

Koko: It really is. An agent that only needs to read invoices must not hold write access to the payments system. Those are two different things and they need to be treated as two different things. And keep the agent's identity distinct from the human's — if an agent is acting on behalf of a user, it gets its own credential with its own limits. A compromise of the agent cannot then impersonate the full authority of the person it serves.

Max: Okay, let me run this through Northwind. The refund agent — how does this play out there?

Koko: Good example. The refund agent's identity is authorized to issue refunds up to the policy cap, and to read the invoice and shipment records it needs. That is it. It cannot change bank details. Cannot move a credit limit. Cannot see another customer's data.

Max: And contrast that with the bad version — the update account tool that was riding standing admin credentials.

Koko: Right. With that one, a single bad call — or a single injected instruction — can redirect a payout, raise a credit limit, rewrite contact information. The blast radius came from the credential, not from the model. The model is not the problem. The permission set is the problem.

Max: Okay, but here is where I want to push back a little, because I know this temptation. What if you just put a firm rule in the system prompt — something like, never change bank details. Does that cover you?

Koko: No. And that is the trap. A prompt is not a control. A stern instruction does not remove the capability — it only asks the model not to use it. And one injection can talk it out of that rule.

Max: So the prompt is saying please don't go in there, but if the credential can reach the door, a compromised prompt can too.

Koko: Exactly. Least privilege makes the dangerous action unreachable rather than merely discouraged. You want it can't — not we told it not to. That is the real distinction.

Max: It can't versus we told it not to. That is a line you could use in a client presentation.

Koko: It is. And speaking of client presentations — let me give you two lenses for your actual work. The first one is the Fortune-500 controls lens.

Max: Segregation of duties.

Koko: Yes. An agent that both approves and disburses has just collapsed a segregation-of-duties control the enterprise spent years building for its human staff. The same SoD matrix that governs people has to govern the agent's identity. The maker and the checker cannot be the same credential.

Max: So when I am reviewing an agent design for a controls-heavy client, I need to map every tool the agent's identity can call against the access-control matrix.

Koko: Map every tool, check it against the SoD matrix, and if the identity is over-scoped — say so plainly. That is a material control gap. Full stop.

Max: And the second lens is private equity diligence.

Koko: The sharpest single question you can ask about any agent in a target or a portfolio company is this: what can this agent's credential actually reach? Not what the demo showed. What the identity is technically authorized to touch.

Max: Because the demo is going to show you the happy path.

Koko: Always. A broad, standing, shared service account is a red flag — because it means the real blast radius is undocumented and probably enormous. A tightly scoped, per-action identity with an audit trail is the signal that an operation has actually reckoned with its downside.

Max: So that one question — what can this credential actually reach — separates an agent you can underwrite from one you cannot.

Koko: That is the line. And it comes back to something simple: every action is attributable. You can audit who the agent was acting as and exactly what it was allowed to touch. That is authentication and authorization done the same disciplined way you would scope a human employee's access. Same rules. Same rigor. No exceptions for agents.

Max: The temp on their first day always gets the room key. Never the master.

Koko: Every time.

Koko: So we have two decisions left in this module, and I want to be honest about how often people get both of them wrong — not because they're careless, but because there's a very tempting shortcut on each one. First decision: where does each piece of work actually belong? There are four levels, and the discipline is to start at the bottom and earn your way up.

Max: Bottom being the most constrained option?

Koko: Exactly. The bottom is deterministic code. Anything that must be exact, validated, or enforced — a calculation, a policy check, an authorization, a schema validation. The model can decide; code enforces. Your refund cap, your entitlement check, your segregation-of-duties gate — those never depend on the model getting it right.

Max: Right, because the model could get it wrong, and that's not a risk you're willing to take on a financial control.

Koko: Correct. The model is probabilistic. Code is not. So anything in the must-be-correct or must-be-allowed category moves out of the probabilistic path entirely. Then one step up: a tool. A discrete, well-contracted action the agent calls — look up an account, issue a refund. Stateless, atomic work. That's a tool.

Max: Stateless meaning it doesn't carry memory of the conversation, it just does the thing and returns a result.

Koko: Exactly right. One level above that is a workflow step — a fixed, coded step in a predetermined chain. When the path itself doesn't need the model to choose it, don't make it agentic. A router or a maker-checker chain you can actually test beats improvised delegation every time.

Max: And then at the top is a sub-agent.

Koko: A sub-agent — another goal-directed agent. And the rule is: default to one bounded agent with a few good tools, and add a sub-agent only when genuine specialization, context isolation, or an ownership boundary makes a single agent provably worse. Not 'possibly worse.' Provably worse.

Max: Here's where I want to push back a little, because when I'm sitting in front of a PE firm describing an automation roadmap, 'multi-agent architecture' sounds sophisticated. It sounds like we're doing serious work.

Koko: And that instinct is exactly the trap. Multi-agent is not a maturity badge you graduate to. It is an architectural tradeoff for real specialization or real ownership boundaries. Reaching for sub-agents because it sounds impressive usually just buys coordination bugs, extra cost, and a larger security surface.

Max: So 'this is a big, important process, it deserves a whole team of collaborating agents' — that's the wrong move.

Koko: That is almost never the first move. The senior move — the one that survives production — is the smallest system that gets the job done. Think of it like staffing an engagement. You automate the timesheet math in code, you hand the team standard templates and tools, you follow a fixed review-and-sign-off routine as a workflow step, and you bring in a specialist partner only when the work genuinely needs a different brain. You would never staff a second partner because it 'feels more senior.'

Max: That analogy is going to stick. So the instinct is: push work down the ladder toward code and tools, and earn every step up.

Koko: That's the one. Every must-be-correct calculation and every must-be-allowed check moves out of the probabilistic path. Prefer orchestration patterns you can predict — chaining, routing, parallelization, maker-checker, orchestrator-worker — over improvised delegation. And a sub-agent is not a better tool. Stateless atomic work stays a tool.

Max: Okay, second decision. The protocol — how the agent actually connects to a tool or another system. I know we've touched on this, but what's the framework for choosing?

Koko: One rule: choose the protocol from the boundary, not the buzzword. Three options. Direct API or function call — that's your default. Your agent calls your function or your service. Simplest, fastest, most controllable, no extra surface. If everything lives inside one team's codebase, that is the right answer.

Max: And an open tool protocol — something like a standard tool-exposure layer — when does that earn its keep?

Koko: When you need to expose or consume tools across an organizational or vendor boundary, or reuse one tool catalog across many agents — interoperability you'd otherwise rebuild by hand. And then agent-to-agent protocols, only when independent agents you don't jointly control must coordinate across a real boundary.

Max: Let me test this with something concrete. Say I'm advising the shared-services team at a PE-backed platform company. They're standing up finance agents across three portfolio companies. How does this play out?

Koko: Perfect example. Inside one portco's own systems — direct calls. Keeps it simple, auditable, cheap. But the moment they want one reusable catalog of vetted, contracted, least-privilege tools consumed by agents across all three companies — now an open tool protocol earns its keep. Build the governed issue-refund-style tools once, with their contracts and scoped identities, and every portco's agents consume the same governed surface.

Max: Because that's a genuine boundary — separate companies, one shared platform.

Koko: Exactly. The protocol is justified because the boundary is real. But if a consultant pitches agent-to-agent orchestration across all three portcos on day one — that's the tempting-wrong answer resurfacing. The boundary that actually exists is a shared tool catalog, not a swarm of negotiating agents.

Max: And for a Fortune Five Hundred client it's the same logic — shared services versus business-unit ownership.

Koko: Right. The protocol boundary should mirror the org boundary. And what makes this powerful for your most demanding clients is this: the tool contract plus the scoped identity together become the control-and-audit story. Central governance defines and owns the tools with least-privilege identities baked in. Business units consume them. Audit gets a governed, traceable surface. That's not a technology detail — that's the answer to the question every CFO and general counsel is already asking.

Max: So the through-line of this whole lesson is literally in that last point. Tools are products. Least privilege shrinks the blast radius. And the boundary tells you which protocol.

Koko: That's it. Engineer those well and the architecture serves the business. Rush past them and you've built something that's hard to audit, hard to govern, and expensive to fix.

Max: Okay, before we close, can we just run the instincts? The things I'm actually supposed to carry out of this lesson?

Koko: Yes — let's do a quick pass. First: treat every tool as a product. Write a contract, scope the identity, test the failure modes. It is not a convenience — it is a governed capability with an owner. Second: least privilege shrinks the blast radius. Every identity gets only what it needs for that task, nothing ambient. Third: push work down the ladder toward code and tools, and earn every step up. The must-be-correct checks live in deterministic code, not in the model's judgment. Fourth: multi-agent is a tradeoff, not a trophy. The smallest system that survives production is the sophisticated choice. And fifth: choose the protocol from the boundary that actually exists — not from the buzzword that sounds impressive in a slide deck.

Max: Five instincts. And every single one has a trap version that sounds reasonable until you say it out loud.

Koko: That's why we named them. The trap is usually the answer that feels like more — more power, more sophistication, more reach. The instinct is the answer that's actually more useful in production. Those aren't the same thing, and knowing the difference is what separates a builder from someone who just assembled parts.

Max: I feel genuinely more equipped to have these conversations with clients. Not just the what, but the why — and the traps to watch for.

Koko: That's the goal. And if you want to keep going — there are guided journeys and hands-on labs waiting for you at KokoAI Academy, at koko knows dot A I. You can take these ideas off the page and actually build with them. Go do that. You're more ready than you think.