Tools
The four ways an agent reaches outside itself — MCP servers, your knowledge base, registered REST endpoints, and messaging channels.
Overview
Read this first — it explains what the four surfaces have in common and where they differ.
On its own an agent can only reason over what is already in the prompt. Tools are how it gets more: how it looks something up, calls a system, or sends a message. Derbee Studio has four tool surfaces, and they exist as separate modules because they solve genuinely different problems — not because the same idea was implemented four times.
Three of them read. The Knowledge Base answers "what do our documents say", the API Registry answers "what does that system currently hold", and the MCP Registry answers both — plus "run this operation for me" — by speaking an open protocol to any server that implements it. The fourth, Channels, is the one that writes: it sends a WhatsApp message, an email, a calendar invite. That read/write split is why channel calls are routed through their own execution node, separate from ordinary tools.
What they share is the surrounding machinery. Whichever surface a call goes through, the platform handles tool schema preparation, relevance filtering, guardrail checks, PII masking and restoration, token accounting and per-step tracing — so adding a tool never means adding that plumbing again.
The four surfaces
All four bind to the same agent and pass through the same guardrail and tracing layer.
Choosing between them
Most integrations have one obvious home. These are the deciding questions.
| Use | When | Direction |
|---|---|---|
| Knowledge Base | The answer is in documents you own — policies, manuals, contracts, past tickets | Read |
| API Registry | A specific REST endpoint already returns what you need, and you just want it called | Read (and write, if you register a write endpoint) |
| MCP Registry | The system exposes an MCP server, or you need several related operations the model can chain | Read and write |
| Channels | The agent must reach a person on WhatsApp or Outlook, or answer messages arriving from there | Write (and inbound trigger) |
Modules
MCP Registry
The Model Context Protocol is an open standard for exposing tools to a language model. Register a server once and every tool it publishes becomes available to any agent you bind it to — MongoDB, Playwright, design tools, internal services, anything that speaks the protocol.
ConnectionFor database servers you can define a constrained tool rather than exposing raw query access. You pick the tool type — Query Tool, Aggregation Tool or both — list exactly which collections are reachable and which fields within them are allowed, and then set hard constraints:
- maxResultLimit — ceiling on rows returned
- allowSorting — whether sorts are permitted
- allowProjectionOverride — whether the model may change the projection
- readOnlyEnforcement — reject anything that writes
Several things happen between "the agent has an MCP server bound" and "a tool actually ran":
Knowledge Base & RAG
A Knowledge Base turns your documents into something an agent can search by meaning rather than by keyword. Upload files or point it at the web; the platform extracts text, splits it, embeds it and indexes it. At query time the question is embedded too, and the closest passages are injected into the prompt — Retrieval-Augmented Generation.
Connection strings and other sensitive fields are encrypted at rest on the knowledge-base record rather than stored in the clear.
IngestionEvery file goes through the same pipeline: detect the format, extract text, chunk it, embed the chunks, store and index them. Each stage is more careful than it first appears.
Three storage backends are supported, and the search path checks the index before querying it.
- Atlas Vector Search — classic per-collection knowledge bases
- Atlas V2 — a single default collection and index
- Chroma — self-hosted collections
- Index status: READY, PENDING, BUILDING or MISSING
- Candidate pool scaled from topK with a floor
- Score threshold plus topK capping
- Single and multi-collection search paths
- Auto-embed or pre-computed query vectors
Content can also come from the open web. Five fetch strategies are available — plain fetch, an HTTP client, two headless browsers, and a naive full-body extractor as a baseline — because a static page, a JavaScript-rendered app and a listing page each need different handling. Readable-content extraction falls back to naive body text when a page has no article structure, and content is capped with truncation flagged so the interface can say so.
Feed URLs get special treatment: Google News and similar redirect wrappers are resolved to the real article URL first, so the crawler fetches the destination rather than the redirect shell.
API Registry
The API Registry is the lightest of the four: register a REST endpoint and it becomes callable. No server to run, no protocol to implement — a URL, a method, headers, query parameters and an optional payload template.
ConfigurationAny part of the URL, query or payload can contain {{token}} placeholders. Token names are restricted to letters, digits, underscore and dot, so stray braces in a payload never match by accident.
At call time the tokens are collected and one cheap model call extracts their values from the user's message. The extraction prompt is deliberately strict: return only compact JSON, and omit any field whose value is not clearly present. Unresolved tokens are left intact in the string rather than blanked, which is what lets the caller detect a missing required value and skip the endpoint entirely instead of sending a half-filled request.
Channels
Channels are the write surface. A channel registration binds a platform account to one or more agents; messages arriving on that account are answered by a tagged agent, and the platform's actions are exposed to the model as tools. A channel is unique per platform and account id, so the same number or mailbox cannot be registered twice.
Agents are attached and detached without touching the agent itself, and a short platform cache keeps repeated tool binds from hitting the database on every turn.
WhatsApp Meta Cloud APIPhone numbers are sanitised before sending — spaces, dashes and brackets stripped, a leading + removed — and anything suspicious is flagged with a specific warning: a leading zero suggesting a missing country code, too few digits, or leftover non-digit characters.
Outlook Microsoft GraphConnection uses a browser OAuth flow with PKCE, a callback secured by state, stored tokens and automatic refresh. Status and disconnect are available without touching the agent.
Inbound security and reliabilityAnything arriving from the internet is treated as untrusted:
- HMAC SHA-256 signature verification per channel secret
- Timing-safe comparison, never a plain equality check
- Missing signature or missing secret both fail closed
- Duplicate message suppression on a one-hour TTL set
- The TTL set is swept on a timer so it cannot grow unbounded
- Delivery status tracking — sent, delivered, read, failed
- Human-readable diagnosis for platform error codes
- Inbound media resolved into agent attachments
How Tools Work — Flow Examples
Four diagrams, one per surface. Each box is a stage the runtime actually has.
Example 1 — An MCP tool call, end to end MCP
Everything between binding a server and a tool actually running. The read-only gate sits deliberately after argument construction, so it inspects what will really be sent.
Example 2 — Ingestion and retrieval RAG
Two pipelines that meet at the prompt. Ingestion runs once per file; retrieval runs on every question.
Example 3 — Filling an endpoint's parameters API Registry
Placeholders are resolved from the user's own words. When a required value is genuinely absent the endpoint is skipped rather than called with a hole in it.
Example 4 — A channel round trip Channels
An inbound message becomes an agent run and comes back out as a platform action. Two gates run before any agent work happens.
Reference Tables
Transports, chunking strategies and the channel tool catalogue.
MCP transports and authentication
| Setting | Values |
|---|---|
| transport | SSE · StreamableHTTP · Stdio · HTTP · WebSocket |
| authType | Bearer Token · Basic Auth · API Key · OAuth 2.0 · No Authentication |
| type | Tool Provider · RAG Source · Workflow Engine |
| resourceType | database · service |
| environment | development · staging · production |
| status | connected · error · disconnected |
Chunking strategies
| Strategy | Best for |
|---|---|
| recursive | General prose — the default |
| fixed | Uniform blocks regardless of structure |
| token | Splitting on token count rather than characters |
| sentence | Short-form content where sentences are the unit |
| paragraph | Documents with meaningful paragraph breaks |
| markdown | Markdown, split on heading structure |
| html | HTML pages, converted to rough markdown first |
| code | Source files — language-aware separators |
| json | Structured JSON, split on object boundaries |
| semantic | Meaning-based boundaries rather than syntax |
Channel tools
| Tool | Required | Purpose |
|---|---|---|
| send_whatsapp_message | to, message | Text or media message. Optional mediaUrl and mediaType for image, video, audio or document |
| send_whatsapp_template | to, templateName | Pre-approved template for business-initiated messages outside the session window |
| Outlook | ||
| send_outlook_message | to, subject, body | Send mail, optional cc |
| read_outlook_messages | — | Read recent inbox messages, top from 1 to 50, default 10 |
| create_calendar_event | subject, start, end | Create an event, optional attendees, location and body |