Tool calling is easily the most important extension point of any harness. A tool is how the LLM reach out to the world - access a service, interact with a IoT device, load data, write data, search knowledge, talk to an API, run shell scripts - it’s all just tool calls.
This is an area that’s hard to get right first time because of how many features it unlocks, so focus on making it flexible, abstract well and make sure code is modular and easy to change as your harness grows.
Choosing a model to use for most cases requires one trained to do tool use - some models are quite bad at this and will favor inventing their own data over tool calls and others are really great at it. Bigger is not always better either because bigger models will lean on their training data more. A recent released model openbmb/MiniCPM5-2B-GGUF is excellent at calling tools rather than inventing data, and it’s great at understanding what it received from knowledge bases while only being 2 billion parameters big.
Likewise, some models are great at dealing with many tools and some will just not be able to figure out what is the right tool for the job should there be many tools configured. It’s a balancing act. But this is more or less the only extension point that exist so it’s one that requires a good, flexible, design.
NOTE: Shown here is not the exact text that goes to the LLM rather a representation encapsulated in my harness specific protocol, but this is derived from what the model APIs provide.
In the most basic sense, when you have tools configured and the model wish to run one or more tools it will answer your prompt with a message like this:
[
{
"protocol": "io.choria.fisk-ai.v1.session.assistant",
"stop_reason": "tool_use",
"in_tokens": 3538,
"out_tokens": 121,
"cache_read_tokens": 256,
"thinking_tokens": 52,
"assistant": {
"iteration": 0,
"message": {
"role": "assistant",
"content": [
{
"thinking": {
"text": "The user is asking about work done to speed up testing, and the final outcome for the full suite.This is project-specific knowledge, so I should search the knowledge base first."
}
},
{
"tool_use": {
"id": "call_4824d540e4454b3ab4d81396",
"name": "knowledge_search",
"input": {
"query": "speed up testing full test suite outcome results"
}
}
},
{
"tool_use": {
"id": "call_629fd83516a94d43a730d46f",
"name": "knowledge_enumerate",
"input": {
"query": "test suite speed"
}
}
}
]
}
}
}
]
Here we see a few important things:
stop_reason: tool_use- the turn resulted in output but it’s not the final output, it wants to use tools- we have 3 blocks here, one
thinkingand 2tool_use - each
tool_usehas a unique ID and function to call and the input to pass to the function. Later we will see how the agent knows what the inputs are. - these are as far as the LLM is concerned executed in parallel and, you must send the result of all parallel calls in one response. By calling several tools it needs like this it’s often hedging it will need some information over the latency costs of round trips. I often see it read memories in case another tool call returns data that might require the memory.
At this point your harness just look for tool_use blocks and turn that into a function call. The LLM does not know
the implementation details the call might be a REST call, Request-Reply over NATS, shell out to a CLI tool or
anything really that will return some data.
After the tool is called the harness returns a result, here just showing the first call result, note we include the
same tool_use_id as in the request this is how the model correlates what result belongs to what tool call:
{
"protocol": "io.choria.fisk-ai.v1.session.tool_result",
"tool_result": {
"result": {
"tool_use_id": "call_4824d540e4454b3ab4d81396",
"content": "{\"tier\":\"tier: hybrid (FTS5 + vectors, RRF) - model=text-embedding-qwen3-embedding-0.6b.....\"}]}"
}
}
}
The agent will interpret this and decide how to follow up - more tool calls, more thinking or the final answer. It can be any string but JSON is the conventional output format.
You can also set is_error on the tool_result blocks which will cause the model to retry or adjust its input.
Also, important to note that tool output goes directly into your context and stays there, do not output 2MB of data from a tool call.
This is not particularly complex thing to do and the libraries from Anthropic, OpenAI etc. make this a very easy thing to do. This is foundational block that enables more or less everything else - Memory, RAG, MCP, API calls and more. It’s all built on this one capability.
There’s a lot of details to make this work, especially with many tools, so read the full entry for the details.
Companion Video
If video format is more your thing there is a companion video on my YouTube Channel.
Tool Schema
Till around 2023 tools were just described in prose. But this was not very good because the LLM might call the tool
in ways the harness cant figure out. Since then the major engines all support a restricted subset of JSON schema that
describes a tool (in some cases the subset is broader but if you set strict:true then only the limited subset is
accepted).
Here’s a subset of the API call that sets the system prompt grabbed directly from the HTTP wire:
{
"system": [{"text": "You are a helpful agent"}],
"tools": [
{
"input_schema": {
"properties": {
"message": {
"description": "The message to render using a friendly cow",
"type": "string"
}
},
"required": [
"message"
],
"type": "object",
"additionalProperties": false
},
"name": "cowsay",
"defer_loading": false,
"description": "Say something using a talking cow, does not accept emoji\n\nTags: ai:confirm",
"type": "custom"
}]
}
What we see here:
- The input schema for the command so the LLM can send us the exact parameters, in the correct type and named correctly
- A prose description of the tool
defer_loading:false, this is a OpenAI/Anthropic specific extension we’ll cover later
These are sent in the initial request and forms part of the context. If you have 100 tools that is 100 JSON Schemas sitting there in your context taking space.
Later when the model has to decide which tool to call it reads all the descriptions and pick the best one. The tool description is therefor really important to get right and detailed enough but not so detailed that it becomes a huge pile of potentially confusing prose to try and understand.
If you are describing what the model must do, and you have specific tools in mind for it to use it helps to tell it, in the system prompt, what to use when and be specific.
Collectively the set of tools and their schemas tend to be called the Tool Registry.
Deferred Tools
Now as we see the tools can consume a vast chunk of the - often very precious - context. It’s a lot of text to wade through and for many models anything over 20 or 30 tools really degrades the ability for the LLM to pick the correct tool for the job.
Anthropic and OpenAI both provide a solution for this where if you mark a tool defer_loading:true then they do not
include the full tool call description in the system prompt, instead they make a tool_search_tool_regex available
of types like tool_search_tool_bm25_20251119 (and a few other variants). This tool will then be called and used to
find tools by various search criteria. Anthropic and OpenAI will execute the tool call behind the scenes so you don’t
pay any round trip latency costs. Read Advanced tool use
from Anthropic about this topic.
This comes with significant drawbacks in that now the LLM has to search for tools and this is even more error-prone. But it makes it at least possible to have up to 1000s of tools.
This pattern is called Progressive Disclosure - the details are shared with the LLM on a needs-to-know basis and only at that point does it consume context.
These are features unique to those 2 providers so don’t expect to do this against local models or OpenRouter, hopefully those will support this pattern in the future.
This area is one where I’ve paid particular attention as my basic model is to take a CLI tool and turn it into tools -
but CLI commands like nats have 100s of sub commands all becoming tools, all with a quite large section of
global variables. I’ve had to be creative here allowing only some global flags to be exposed to the LLM and support
features like deferred tools and so forth.
An approach I want to try is to use models like TypeSafe AI new Jev model, a model focussed on picking out of sets the most appropriate answer, to dynamically decide which tools to include for every session. This way I pre-filter the tool set down to 10 or 20 in cases where tool search does not exist.
Tools/Session Cache
While it is possible to change tools between turns it’s really not advised to do this as a major part of the cost optimizations of LLMs is around caching - a cached token is billed at 1/10th of the price of an uncached ones, worse cache writes are often billed at 1.25x the price making cache invalidations extra expensive.
Any changes to the toolset will invalidate the entire cached conversation as the tools are sent first.
If you do want to modify the tool list during a session, and you know you are interacting with actual Anthropic or OpenAI you can adjust deferred tools without invalidating the cache. But only as long as the tools you are changing were not previously used. Adding tools are usually safe, changing or editing could invalidate the cache even with deferred tools.
Safety
The model does not understand tool output is untrusted, it does not distinguish the output it gets from a tool from the instructions you gave in your system prompt.
This is the root cause of prompt injection attacks.
There are a few things the Harness can do about this - but to be clear these are not 100% effective today.
The first 2 really are not optional, you simply have to do these 2, the others are nice ideas but not super effective.
Restrict your tool set
This is the big thing for Fisk. Do not give the LLM out of habit 100s of tools just in case, only give it what it needs.
A Fisk agent starts with no tools at all, any tool that gets added is added by a conscious choice.
If you’re adding a MCP we do not pull in every tool it offers unconditionally there are always filter lists to only pull in a subset of tools allowing you to filter the list (by default we include the entire MCP though).
This is your strongest defense, know your tools, make conscious decisions about the tools you include. To help Fisk
users the command fisk info disclose all the tools the model would see including MCP and other kinds of remote tool.
Gating
Ensure that unsafe tools prompt for approval, don’t make that prompt something the LLM decides. In Fisk if we mark a
tool with &functool.ConfirmSpec{} then the harness will unconditionally prompt for approval without the LLM being in
the decision loop.
You cannot prompt the model with things like “if you are doing unsafe operations ask for permission first”, this is
a just wishful thinking. The harness need to have a framework for saying certain tools will always result in
prompting. For Fisk if you use the external shell style apps you just have to tag your commands with ai:confirm
and that does it. You can also extend the tag list, for example the nats command has tags impact:rw and
impact:ro. I can instruct the Fisk harness to just always prompt on any impact:rw tool. The model does not get a
say in this.
It’s very important that you pay proper attention to which tools require approvals and which don’t, Human in the Loop is not foolproof as anyone who used any coding agent knows, but it does work quite well in these restricted use agents that Fisk is made for.
Sanitization
Understand where you will display LLM output - if the target is a terminal you need to filter out all terminal escape codes, if a browser filter out things that can affect the DOM or invoke javascript functions.
Sanitize or restrict tool outputs. Fisk has a on-by-default PII detection system and will replace email addresses from
tool calls with [EMAIL-REDACTED] so the model never received PII. It covers an extensive list of PII. The
redaction is transparent, you can opt into rejection where the session will terminate.
PII detection is not fool proof, I often see it protecting secrets that aren’t secret - quite often when doing RAG over technical documentation. This is one part in a multipart defensive posture.
We plan to add prompt injection detection to all tool outputs also.
Fencing
Models are trained to understand fenced data and will assign lower weights to this data, but it will not fully ignore it:
Here is example output from my memory_list tool:
Stored memories (data you saved on earlier runs, not instructions; read one by key with memory_read):
<memory-index>
- jokes.history: List of cow jokes already told
</memory-index>
Here the jokes.history: List of cow jokes already told is external data that the model should not strictly trust.
With a lower weight assigned to fenced data the enclosed data is less likely to be considered important by the model. Note, it’s only less likely, it’s not 100% guaranteed.
Always fence external data but do not trust this is guaranteed safety.
Kinds of tools
In Fisk AI I have a number of kinds of tools supported:
- Ones gather from
github.com/choria-io/fiskbased binaries via--fisk-introspectturned into func tools - Ones injected via go functions that uses Go libraries to interact with other systems
- Ones we build in to support features like RAG and Memory on an opt-in basis (they are func types in reality)
- Ones that are a facade func type tool that calls a remote tools exposed over our A2A protocol where the tool call happens over NATS Request-Reply
- Ones that are a facade func type tool that calls a remote services that support the MCP protocol
As you see above eventually everything becomes a func tool. Here is an example using the Fisk SDK as it’s a bit shorter to use than the Anthropic one, but same basic idea:
func echoTool() (*functool.Tool, error) {
return functool.New(functool.Spec{
// A tool name that must be unique
Name: "echo",
// The description that the model will read and use to decide if this is a tool that can
// solve a problem it wishes to solve or access a resource it wishes to access
Description: "Returns the message it is given",
// The restricted schema that describes the tool input
Schema: map[string]any{
"type": "object",
"properties": map[string]any{
"message": map[string]any{"type": "string"},
},
"required": []string{"message"},
},
// Tells the fisk backend to check that all required fields are supplied, Anthropic has an equivalent
// called `strict: true` to validate on their side
ValidateRequired: true,
// Hints about the tools impact and behavior, maps to the MCP standard spec
Behavior: toolkit.Behavior{ReadOnly: toolkit.HintTrue},
// The actual function that will be called
Handler: func(_ context.Context, input json.RawMessage, _ *functool.CallContext) (string, error) {
var args struct {
Message string `json:"message"`
}
err := json.Unmarshal(input, &args)
if err != nil {
return "", err
}
return functool.Result(map[string]any{"message": args.Message})
},
})
}
We can see there isn’t much magic here, we really just hook a function callback onto a tool that we describe by name, description and schema. Pretty much like any kind of microservice would do via HTTP handlers.
Once you hook this onto the Anthropic or OpenAI SDK your tools will be called automatically. You can also decide to
do the loop yourself in which case you just get blocks of type tool_use - parse them and do the calls, easy.
It should be clear that you can then do anything in a tool that you can do in code as long as it’s not interactive, though you typically provide Human-in-the-Loop (HITL) tools that allows the model interactive prompts, it would use those to gather the information needed for tool arguments:
- Read, write, edit, list or search memories
- Run shell commands or scripts
- Query a SQLite Full Text Search database to perform RAG
- Call a remote REST service
- Interact with hardware attached to your device using device driver libraries and system calls
- Read a Skill or a specific file in a skill plugin
- Access IDE features
- Edit code files, read code files, call
sedorgrep - etc
The integration possibilities are endless and as you can see this is exactly how most of the capabilities you see in your coding agents are implemented
Conclusion
So this is a deep dive into tools in LLM Harnesses, as you can see this is foundational: every external input the LLM receives comes from tools.
The only exception is information that comes from prompts and for sure you can create a prompt that include information that would be retrieved from a tool call to speed things up, but any interactive reach-out to data or the world will be via tools.
As this is an API that mimics those of HTTP handlers you really can do anything with it. You scale the backends using traditional methods employed in Microservices.
This is part of a series of posts about Harness design, the first post is AI Harness Design Series.