Custom tools

Tools are how Stoa reaches out of the chat window and into your real systems. When an agent answers a question, looks up a record, or kicks off a downstream action, it's using a tool. This page is for integrators who want to understand what a tool is, what makes a good one, and how it gets connected to Stoa.

What a tool is

From an integrator's perspective, a tool is a small, named capability that Stoa can call to interact with one of your systems. It has a clear input, a clear output, and a single job. Tools are the bridge between the language model and the rest of your stack.

Common tools that customers connect include:

• Database lookups. Pull a customer record, an inventory level, a project status, a grant balance.
• Internal API calls. Query an HRIS, an LMS, a ticketing system, a CRM, or a homegrown line-of-business app.
• File operations. Fetch a document from a network share, a content repository, or an object store.
• Trigger a downstream workflow. Kick off an automation when an agent decides it's needed.
• Search against legacy systems. Wrap a search endpoint that the agent can hit instead of guessing.

A tool is not a replacement for a knowledge base. If the answer lives in documents, index them as a knowledge base. Reach for a tool when the answer lives in a system that holds live, changing state.

Connecting a tool server

Stoa speaks MCP (Model Context Protocol), the open standard for giving a model tools to call. A deployment connects to a single MCP server, configured from the Integrations screen in the admin UI, under MCP Server.

That one connection is meant to be an aggregation point. Most teams don't wire Stoa directly to each individual backend; instead they put something in front (a workflow-automation platform or a small gateway that speaks MCP) and expose everything through that one endpoint. So "one server" in Stoa's configuration can still mean dozens of individual tools underneath it.

To connect it, an admin fills in:

• Transport. Streamable HTTP or SSE. Pick whichever your MCP server supports.
• Server URL. The address of the MCP endpoint.
• Headers. Any authentication headers the server needs, added as name/value pairs (a bearer token in an Authorization header is typical). Once saved, header values are masked in the UI and left alone unless you change them.
• Enabled. Toggle the connection on or off without deleting the configuration.

Before saving, click Test Connection to open a temporary session against the server, confirm it responds, and see how many tools it offers. Once connected, Reconnect re-establishes the session on demand, and every individual tool the server exposes shows up in the Tool Catalog.

Because there's a single connection per deployment, you can't register a second, independent MCP server alongside the first. If you need tools from more than one internal system, aggregate them behind the one server you point Stoa at.

If your systems don't speak MCP yet, that's a gap on your side to close rather than something Stoa builds for you. Your engineering team (with help from your delivery engineer, if you want it) stands up an MCP server in front of whatever needs to be reachable, and Stoa connects to it the same way once it's live.

What makes a good tool

If you're the one building or configuring the MCP server Stoa connects to, the tools that work best in practice share a few traits.

• Single responsibility. One tool, one job. lookupCustomer and createTicket are two tools, not one with a mode parameter.
• Predictable inputs. Required fields are required, optional fields have defaults, and types are explicit.
• Clear outputs. Return structured data with the fields the agent needs. Avoid raw HTML or paginated payloads the agent has to parse.
• Predictable side effects. A tool that writes data should say so in its description. Surprise mutations break trust.
• Scoped permissions. A tool should call your system with the narrowest credentials that still let it do its job.

Choosing which tools an agent can see

Access is granted per tool, not per server. On an agent's create or edit screen, the Tools field lists every individual tool available from your connected MCP server, alongside Stoa's own built-in tools, and an admin picks exactly the ones that agent should have. A finance agent might get lookupBudget and nothing else; a legal agent might get lookupContract and nothing else, even though both tools arrive through the same connection. See Roles & permissions for the wider permission model, and Tools for how a granted tool actually shows up to end users in chat.

What happens if the server goes down

If a chat needs a tool and the connection has gone stale, Stoa reconnects once automatically and retries the call. If that also fails, the tool call fails and the agent's reply says which tool failed and why, the same way any failed tool call surfaces in chat.

Connecting to the server is capped at around 10 seconds, and an individual tool call at around 30 seconds, so a hung server shows up as a timed-out call rather than a chat that never finishes. If the server happens to be down when Stoa itself starts up, that's logged and skipped: the rest of the platform still comes up normally.

From the Integrations screen, an admin can force a fresh connection at any time with Reconnect, which reports how many tools came back, or a warning if the server offered none.

Testing a tool

Test Connection, in the connection form, confirms the server is reachable and reports how many tools it returned. It doesn't exercise a specific tool end to end. To see a real round trip, grant the tool to an agent and ask a question that should trigger it: the call shows up inline in the chat, with the input Stoa sent and the result it got back (see Tools). That's the fastest way to confirm a tool behaves the way you expect before rolling it out to a wider group.

Next

• Webhooks for the inverse direction: events leaving Stoa.
• Building skills for combining tools into reusable workflows.
• Tools (user view) for how tools appear to end users in chat.