Add an external tool

Tools are what turn an agent from a chatbot into a system that does work. This guide explains how to connect an agent to an external capability while keeping the integration governed and observable.

Choose an integration pattern

Pattern	Use when
Built-in provider	The system you need is already supported by the runtime.
MCP server	You want a standard, reusable tool server that multiple agents can share.
Llama Stack tool group	You are standardizing on Llama Stack in your environment.
A2A agent	The capability is itself another Alquimia Platform agent.
Custom Python module	You need business-specific logic that lives inside the runtime.

Design the tool contract

Before integrating, define the contract clearly:

What does the tool do in one sentence?
What are its inputs, outputs, and error conditions?
Does it have side effects? Can it be retried safely?
What data will it expose to the LLM?
Who can invoke it, and under what conditions?

A clear contract makes the tool easier for the agent to choose correctly and easier for you to audit later.

Register and connect the tool

Store any credentials the tool needs as registry secrets.
Add the tool configuration to the agent spec, choosing the appropriate adapter and pointing to the tool endpoint or module.
Describe the tool well. The agent selects tools based on name and description, so be explicit about inputs, outputs, and side effects.
Test in isolation with a sample prompt that should trigger the tool. Check the worklog for the exact input sent and output returned.
Add governance controls such as shields, role restrictions, or approval gates before exposing the tool to real users.

Govern the tool

Not every tool should run automatically. Consider:

Role tier — limit sensitive tools to agents with an operator role.
Approval gate — require human confirmation before destructive or financial actions.
Shield checks — block or flag requests that look like prompt injection or policy violations.
Rate limiting — prevent runaway loops or excessive calls to expensive APIs.

Classify operations for Zero Trust authorization

In production, Alquimia Platform uses a DefaultToolAuthzPolicy(default_deny=True). An unclassified tool denies every operation, so each tool must declare what it can do and who may invoke it.

Classify operations with the CLI:

alquimia registry tools set-operation filesystem-tools "read_*" \
  --match glob --severity read-only --tier-grants reader,editor,operator

alquimia registry tools set-operation filesystem-tools "delete_*" \
  --match glob --severity destructive --tier-grants operator \
  --requires-approval

Severity acts as a tier floor:

Severity	Max grantable tier
`read-only`	`reader`, `editor`, `operator`
`mutating-recoverable`	`editor`, `operator`
`destructive`	`operator` only

The runtime resolves the most specific matching operation, then checks whether the agent’s role is in tier_grants and not excluded by severity. An agent can further narrow its own access with tier_ceiling in the agent spec, but it can never widen access beyond the registry grants.

Inspect what a tool can do at runtime:

alquimia registry tools inspect filesystem-tools --for-tool "read_file"

Observability

Every tool invocation is recorded in the worklog with the input, output, error, and latency. Use this to detect drift, audit access, and tune tool descriptions when the agent chooses poorly.