Custom tools

Agents in Fosnie can use three kinds of tool: built-in native tools (web search, code interpreter and the rest), MCP servers you connect, and custom tools you define yourself. This page covers custom tools and where to manage them.

What a custom tool is

A custom tool is a declarative HTTP call you register once, and an agent then calls by name during its reasoning loop. You give it:

• a name, display name, and description (the description is what the model reads to decide when to use it);
• a parameters schema (JSON Schema) describing the arguments the model must fill;
• an endpoint config – the URL, method, headers, and body, with {{param}} placeholders substituted from the model's arguments at call time;
• an optional auth secret, held encrypted in the keyring and never returned to the model;
• response handling – return the raw body or extract a field by JSON Pointer, size-capped so a runaway endpoint cannot exhaust memory;
• flags: requires egress (does it reach outside the perimeter), side-effecting (does it change state), and a timeout.

Every tool is versioned and admin-approved. Dispatch runs through the same zero-egress choke-point and dual-mode SSRF guard as MCP, and any failure is returned to the model as structured text so a bad call lets it recover rather than aborting the turn.

Activate custom tools

1. Turn on the connector. Custom tools have a deployment-level kill-switch. In Admin → Integrations, enable Custom tools (integration.custom_tool.enabled). While it is off, no custom tool runs.
2. Create the tool. In Admin → Tools (requires the tools.manage permission), add a tool: name, description, parameters schema, endpoint, auth, and the flags above. Test-run it against sample arguments before enabling.
3. Enable it, then add it to an agent so that agent may call it. An agent only sees the tools on its list.
4. Approvals. A tool marked side-effecting pauses for human approval in the chat ("Run custom tool X?") before it executes; read-only tools run without a prompt.

The Tools admin (CRUD)

The Admin → Tools tab is the full management surface. It also lets you toggle native tools on or off and override their descriptions. Behind it:

All of these require tools.manage and every change is written to the audit log.