Module Deep Dive

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.

MCP Registry Knowledge Base API Registry Channels Agent Run Answer guardrails · PII masking · tracing · token accounting three read · one writes
Four surfaces, one execution path — the surrounding machinery is shared

Choosing between them

Most integrations have one obvious home. These are the deciding questions.

UseWhenDirection
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.

Connection
transport
How to reach the server: SSE, StreamableHTTP, Stdio, HTTP or WebSocket.
authType
Bearer Token, Basic Auth, API Key, OAuth 2.0, or No Authentication. OAuth runs a real browser consent flow with pending-state pruning and automatic token refresh before each use.
type
What the server is for — Tool Provider, RAG Source or Workflow Engine.
resourceType
database or service. Database servers get extra handling: connection auto-setup and a database override.
environment
development, staging or production — so the same logical server can be registered per environment.
tools[]
Each discovered tool with its name, description, cached input schema and an isEnabled switch. Disabled tools are never offered to the model.
instruction
Free-text guidance for the tool planner. It takes priority over the planner's own ordering and inclusion rules — the documented way to force a tool always to run, or always to run after another.
timeout retryPolicy
Per-registry call timeout and retry count. status tracks connected / error / disconnected.
Custom database tools

For 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
Read-only enforcement is checked at call time, not trusted from the prompt. Before a tool runs, its arguments are inspected. An aggregation containing $out or $merge is rejected, as is any call whose top-level arguments include a write-intent key — update, insert, delete, upsert, $set, $push, $pull, $unset, $inc or $addToSet. The call fails with an explanation rather than silently executing.
Runtime behaviour

Several things happen between "the agent has an MCP server bound" and "a tool actually ran":

Caching
Loaded tools and their schemas are cached per registry for five minutes, so a conversation does not re-list tools on every turn.
Schema sanitising
Strict models reject non-standard schema fields, so vendor extensions, $ref, $defs, deprecated and heavy metadata are stripped before the schema is offered.
Optional-property pruning
Optional parameters the model never uses still cost tokens on every turn, so they are pruned down to the required set plus an allowlist, and the required array is re-synced to what survived.
Planning
One call decides which tools to run and in what order. It is explicitly taught about dependency chains: if a tool consumes something an earlier tool produces, both are included with the producer first — and when in doubt it is told to include both rather than drop the consumer.
Argument repair
If a required parameter is still empty, it is filled from earlier tool results by matching names three ways — exact, default-prefixed, and fuzzy root overlap. It only fills on a confident name match and never overwrites an existing value, so arguments are not invented.
PII restoration
Values masked before the model saw them are restored inside tool arguments just before execution, so the downstream system receives the real value while the model never did.

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.

Ingestion

Every 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.

Format detection
Extension first, MIME type second. Dispatches to PDF, DOCX, spreadsheet, image or plain-text handling — including source files such as .ts, .py, .sql, .yaml and .json.
Extraction
PDFs can additionally have their embedded images described by a vision model. Scanned pages and image files go through OCR, with the language set per deployment and the trained models cached rather than re-downloaded.
Failure classification
When nothing is extracted, the reason is recorded — no_text means the parser ran and the file genuinely has none, which is worth a vision fallback; read_failed means it never parsed, where a fallback would only mask the problem.
Chunking
Ten strategies with configurable size and overlap. Content type can be auto-detected with a confidence rating and a stated reason, and code chunking maps your language name onto the right separator set.
Embedding
Documents are embedded in parallel. Jobs are tracked and cancellable, errors are classified rather than surfaced raw, and Google embeddings are dimension-adjusted so vector sizes stay consistent.
Search

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
Why the readiness check matters. A vector index that is still building returns nothing rather than failing. Checking status first turns a silent empty result into a logged, explainable skip — the same class of problem as the dimension mismatch handling in template search.
Web sources

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.

Configuration
url
HTTPS is enforced at the model level. A non-HTTPS URL is rejected on save with an explicit validation error, so a plaintext endpoint cannot be registered at all.
method
GET, POST, PUT, DELETE or PATCH.
queryParams
Key, value and an optional description — the description is what lets a parameter be understood rather than guessed.
headers
Static key/value pairs sent with every call.
payload
A static or templated JSON body.
responseStructure
Stored metadata describing the response shape, so callers know what to expect without a live call.
callback
An optional second request fired after the main one — its own URL, method and headers. Useful for acknowledgement or notification hooks.
Dynamic parameters

Any 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.

The extraction call is always billed and traced — including when its output fails to parse. Token usage is returned even on a parse miss, so a failing extraction shows up in analytics rather than quietly costing money.

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 API
send_whatsapp_message
Send text or media — image, video, audio or document — to a number in international format. Media paths are resolved to public URLs automatically, and the tool description explicitly forbids the model inventing a URL that did not come from attachment data or a tool result.
send_whatsapp_template
Send a pre-approved template. This is the path for business-initiated messages outside the 24-hour session window, where a plain message would not be delivered. Placeholder values can be supplied per call or fall back to the channel's configured defaults.

Phone 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 Graph
send_outlook_message
Send mail from the connected mailbox — recipients, subject, body and optional CC, comma-separated for multiples.
read_outlook_messages
Read the most recent inbox messages, one to fifty, defaulting to ten.
create_calendar_event
Create an event with subject, ISO 8601 start and end, and optional attendees, location and body. Times are read as UTC unless a zone is included.

Connection 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 reliability

Anything 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
Secrets are masked on read. Access tokens, app secrets, API keys, client secrets and refresh tokens are replaced with a dotted mask plus the last four characters whenever a channel configuration is returned — so the configuration screen stays useful for identifying a credential without ever handing it back.

How Tools Work — Flow Examples

Four diagrams, one per surface. Each box is a stage the runtime actually has.

Input / output Data handling Model / decision Gate / side effect Result

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.

$out · $merge · $set · update strips $ref, $defs, vendor fields fills from earlier results 5-min cache User Request Load Tools Sanitise + Prune Schema Tool Planner Argument Builder Read-only Check Blocked Execute Tool Restore PII in Args Tool Output
Cache → sanitise → plan → build args → gate → execute → unmask

Example 2 — Ingestion and retrieval RAG

Two pipelines that meet at the prompt. Ingestion runs once per file; retrieval runs on every question.

INGESTION RETRIEVAL Atlas · Atlas V2 · Chroma Upload file or URL Detect format Extract text · OCR · vision Chunk — 10 strategies Embed in parallel Store + index User question Embed query Index readiness check Vector search Score threshold + topK Matched passages Grounded context
Index once, query often — the readiness check turns a silent empty result into a logged skip

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.

value not clearly present HTTPS enforced on save optional callback fires after User message Registered endpoint Find placeholders Extract values — one call All required filled? Skip endpoint Call endpoint Response data
Unresolved placeholders stay intact, which is what makes the skip detectable

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.

already seen HMAC · timing-safe 1-hour TTL set WhatsApp or Outlook Inbound message Verify signature Duplicate check Drop Normalise message Agent run Channel tool call Platform API Delivered + status
Verify, de-duplicate, then run — outbound side effects go through their own node

Reference Tables

Transports, chunking strategies and the channel tool catalogue.

MCP transports and authentication

SettingValues
transportSSE · StreamableHTTP · Stdio · HTTP · WebSocket
authTypeBearer Token · Basic Auth · API Key · OAuth 2.0 · No Authentication
typeTool Provider · RAG Source · Workflow Engine
resourceTypedatabase · service
environmentdevelopment · staging · production
statusconnected · error · disconnected

Chunking strategies

StrategyBest for
recursiveGeneral prose — the default
fixedUniform blocks regardless of structure
tokenSplitting on token count rather than characters
sentenceShort-form content where sentences are the unit
paragraphDocuments with meaningful paragraph breaks
markdownMarkdown, split on heading structure
htmlHTML pages, converted to rough markdown first
codeSource files — language-aware separators
jsonStructured JSON, split on object boundaries
semanticMeaning-based boundaries rather than syntax

Channel tools

ToolRequiredPurpose
WhatsApp
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