A tool gateway offers an attractive developer experience. Connect once, discover many tools, and get common metering and telemetry for free. Integration work drops, and the platform team gets one place to apply policy instead of chasing it through every agent's code.
The same gateway can become a privileged bridge between your agents and dozens, or thousands, of external operations.
If a broad credential leaks, whoever holds it inherits the gateway's reach. If the gateway sends a call to the wrong place, the downstream system still experiences the action. If the gateway goes down, every agent behind it fails at once. And if its catalogue changes without anyone reviewing it, an agent can discover an operation nobody ever approved.
So the gateway is a control point. It is not proof that every action passing through it can be trusted.
One key, many tools
The pattern is no longer hypothetical. The walkthrough discussed in Part 1 used treg, which describes itself as "OpenRouter for agent tools": one credential in front of thousands of tool endpoints from about a hundred providers, paid per call. Products like this are a reasonable answer to a real problem: every agent team otherwise ends up managing its own pile of API keys, rate limits and invoices. Naming one here is not an endorsement. The questions in this part apply to any gateway, whether you buy one, run an open-source one, or build your own in front of internal APIs.
The convenience and the concentration of risk are the same property. The rest of this part is about keeping the first while managing the second.
Weaverbird Agri is fictional, and its systems and figures are illustrative. Weaverbird runs its two agents, Scout and Depot Desk, behind a model and tool gateway that does metering, policy and the tool catalogue. Scout, the market-research agent, mostly calls public search and data tools. Depot Desk, the dealer-service agent in the dealer portal and on WhatsApp, reads the ERP and drafts credit notes for short deliveries. Those two agents sit at very different points on the risk scale, and the gateway treated them the same way until a review in the second quarter.
Separate the control plane from the data plane
The control plane decides:
- which agent can discover which tool;
- which operations are allowed;
- which parameters and data classifications are permitted;
- which identity is delegated, and with what scope;
- whether a person must approve the action first;
- which budget and rate limits apply;
- which regions and providers are approved.
The data plane executes the approved call. The downstream tool must still authenticate the caller, authorise the specific operation, validate input, enforce its own transaction rules and record its own evidence. A gateway that says yes does not relieve the ERP of saying no.
This split matters most when something goes wrong. If policy lives only in the gateway, a single misconfiguration or bypass removes every control at once. If each downstream system also defends itself, a gateway mistake becomes a contained incident instead of an open door.
It also matters for cost, as Part 1 showed. Weaverbird's gateway totals never matched its provider invoices, partly because the ERP connector Depot Desk uses is called directly from the orchestrator and never passes through the gateway. That was a metering gap. It was also a control gap: whatever policy the gateway applied did not apply to the most sensitive system Depot Desk could reach.
The least-authority pattern
Avoid giving an agent a long-lived credential that represents a powerful service account. Prefer:
- short-lived credentials;
- delegation of the user's or workload's identity, so the call carries who is actually asking;
- scopes per agent and per tool;
- permissions per operation, not per system;
- restrictions by resource and tenant;
- constraints on parameters, such as a maximum amount or an allowed account list;
- spend and transaction limits;
- just-in-time elevation for rare tasks;
- explicit confirmation for high-impact actions.
The difference between "may read invoices" and "may create and pay suppliers" is too important to hide inside one generic "finance tool" permission.
Weaverbird's original Depot Desk build had exactly that problem. To move quickly, the team connected it to the ERP with one service account that had write access across the finance module. In practice Depot Desk only needed three things: read stock, read orders and deliveries, and create a draft credit note. The review replaced the single account with three narrowly scoped permissions and nothing else. Depot Desk still cannot issue a credit, change a customer's credit limit or make a payment, and now that is enforced by the ERP rather than only promised in the agent's instructions. Draft credit notes up to R5,000 go to a depot manager for one-click approval; anything larger goes to the credit controller.
For more on identity, see identity before intelligence, and for how authority and tool contracts change an agent's risk boundary, agents change the risk boundary.
Read tools and write tools need different treatment
Not every tool deserves the same controls. A sensible default ranks tools by the authority they carry.
| Tool class | Example | Default treatment |
|---|---|---|
| Public read | Search public documentation or price data | Allowlisted, with rate and cost controls |
| Internal read | Retrieve a customer record | Identity, purpose and data controls |
| Reversible write | Create a draft ticket or draft credit note | Confirm scope; retain change evidence |
| External communication | Send an email or message | Preview, recipient verification and approval |
| Financial action | Initiate a payment, purchase or credit | Strong authentication, limits and human approval |
| Infrastructure change | Deploy or delete a resource | Change control, plan preview, rollback and approval |
| Irreversible action | Delete a regulated record | Normally blocked from autonomous execution |
The ladder also tells you where to spend design effort. Weaverbird's Scout lives almost entirely on the top rung, so its controls are mostly about cost and rate. Depot Desk touches internal data and writes drafts, so its controls are about identity, scope and approval.
Retries and idempotency
Partial failure is normal, and retries are the usual answer. A retry is safe for an idempotent read. It is not automatically safe for anything with a side effect.
Weaverbird found this out the mild way. A slow ERP response caused Depot Desk to retry a draft credit note request, and the depot manager's approval queue showed two identical drafts for the same short delivery. The manager noticed and rejected one. Had the tool issued credits instead of drafts, the dealer would have been credited twice.
The fix was an idempotency key: each credit note request carries a key derived from the delivery and the dealer query, and the ERP rejects a second request with the same key. Consequential tools need idempotency keys, transaction references, or a confirmation step before repeating. That rule belongs in the tool contract, not in the agent's good intentions. Part 3 covers the other half of partial failure: what the answer should say when a call does not succeed.
Tool discovery is a policy decision
Dynamic catalogues are useful because the agent can find capabilities at runtime. They introduce uncertainty because the set of available tools can change after the agent was tested.
Weaverbird's gateway made new tools visible to every agent by default. During the review, the team found a document conversion tool that someone had listed for a different project. Scout had never used it, but nothing stopped it from doing so, and nobody had checked where it processed files or what its terms said about retention. The gateway now lists tools to agents by allowlist, and a new tool enters the catalogue only after a named owner approves it.
In production, control:
- approved tool and provider versions;
- schema changes;
- new operations on existing tools;
- dependency and licence review;
- data-processing terms, including retention;
- geographic processing and residency;
- service availability and recovery;
- deprecation and rollback.
Data-processing terms matter under POPIA. When an agent sends a dealer's personal information to an external tool, Weaverbird remains the responsible party and the tool provider is acting as its operator. That relationship needs a written agreement and security safeguards whether the call goes through a gateway or not.
Pinning a version is not enough if the provider changes behaviour behind the same endpoint. Contract tests that run on a schedule, and a controlled rollout for tool changes, are what catch that.
What the evidence record should show
For every consequential tool call, retain:
- the requesting user and the agent's identity;
- the delegated identity and its scopes;
- the tool, operation and version;
- the policy decision and the reason for it;
- the approval and the approver, where one was required;
- the input's classification and a safe reference to the request;
- the result, any side-effect identifier and its status;
- retry and idempotency information;
- cost, duration and provider;
- the trace link to the final answer or action.
Protect this record from inappropriate change. Audit data needs its own access control too: it can hold sensitive operational detail, and sometimes personal information.
When a dealer in Welkom disputed a credit note three months later, Weaverbird could show who asked, what Depot Desk drafted, which delivery it referred to, who approved it and when. That is the purpose of the record. It is not a compliance artefact for its own sake; it is how the business answers a reasonable question without a week of reconstruction.
Gateway design questions
- What happens to every agent when the gateway is unavailable?
- Can an agent bypass it through a direct SDK call or network route?
- Are credentials scoped to the agent's real purpose?
- Who approves a newly listed tool?
- Can a tool receive data from the wrong tenant or region?
- Can a retry duplicate an action?
- Does the downstream system enforce its own authorisation?
- Can an emergency revocation take effect immediately?
- Can telemetry and billing be reconciled independently of each other?
- Can the organisation investigate a disputed action months later?
The short version
One key to many tools is a convenience and a concentration. Treat the gateway as a control point, not a trust boundary.
Decide in the control plane, defend in every tool. A gateway's yes does not replace the downstream system's own authorisation.
Scope by operation, not by system. "Draft a credit note" and "pay a supplier" are different permissions.
Make side effects idempotent. A retry should never pay twice.
Treat discovery as policy. A tool nobody approved should not be visible to an agent.
Previous: Part 4, memory is a governed data product. Next: Part 6, evals that gate real work. All parts are on the series page.
How CloudNala can help
We review agent tool access the way an attacker and an auditor would: mapping every tool an agent can reach, splitting broad service accounts into operation-level permissions, finding the calls that bypass the gateway, designing approval steps and idempotency for consequential actions, and defining the evidence record each call should leave. The result is a gateway design your security team can sign off and your engineers can still build on quickly.
Work with CloudNala
CloudNala helps organisations move from technology ambition to practical execution across cloud, AI, data, platform engineering and digital services.
Whether you are exploring AI, modernising your cloud environment, building a public-sector digital service, or turning an idea into a working MVP, we can help you shape the roadmap and deliver the next step.
Book an Agent Evidence Review or write to us at consult@cloudnala.co.za