| name | add-tool |
| description | Add a new MCP tool to this WhatsApp server. Use when asked to expose a new capability, wrap a new bridge endpoint, or add a tool to tools.py or scheduling.py. Covers annotations, the confirm guard, core-set placement, retrieval aliases, and the eval case. |
Adding an MCP tool
Five steps. Skipping step 3 or 4 produces a tool that exists but that the model
can never find, which is the same as not shipping it.
1. Write the tool
Tools live in whatsapp-mcp-server/tools.py (general) or scheduling.py
(queue, drafts, notes). Register with @mcp.tool(annotations=...) using one of
the five constants defined at the top of tools.py:
| Constant | For |
|---|
READ_LOCAL | Reads the local store. No network, no side effect. |
READ_BRIDGE | Reads via the bridge (touches the network), no side effect. |
SEND | Sends a message or file, non-idempotent. |
MUTATE | Changes state, recoverable (react, mark read, edit). |
DESTRUCTIVE | Irreversible: delete, revoke, leave, block. |
A DESTRUCTIVE tool takes confirm: bool = False and calls _require_confirm
before doing anything:
@mcp.tool(annotations=DESTRUCTIVE)
def delete_thing(thing_id: str, confirm: bool = False) -> dict:
"""One-line summary the model reads.
Args:
thing_id: ...
confirm: Must be True. The user, not the LLM, has to have agreed.
"""
if (denied := _require_confirm(confirm)) is not None:
return denied
...
The annotation is only a hint to the client. The confirm kwarg is the actual
enforcement, and it exists because older MCP clients do not support elicitation.
Clamp every caller-supplied bound. The existing tools use limit <= 100,
context windows <= 20, message body <= 65536 bytes. Match them.
2. Decide whether it belongs in the core set
_CORE_TOOLS in server.py is the 29-tool hot core served directly in the
default minimal toolset. Every entry there is paid for on every request to the
model, whether or not WhatsApp is touched.
The bar: would a typical session use this in the first three calls? If not, leave
it out. It stays fully reachable through find_tool / call_tool. Most new
tools should not be in the core.
3. Make it findable
If the tool's name and description do not share vocabulary with how a person
would ask for it, find_tool cannot rank it. schedule_message never lexically
matches "send this tomorrow morning".
Add an entry to _ALIASES in toolsearch.py:
"your_tool": "the words a user would actually say for this thing",
Write real phrasings. Do not copy strings out of the eval cases. An alias map
tuned against its own answer key measures nothing.
4. Add an eval case
Append to tests/toolsearch-eval/cases.json:
{"q": "how someone would phrase the task", "gold": "your_tool", "alts": ["a genuinely correct substitute"]}
alts is for tools that would also be a right answer, not near misses. Then run
the eval and confirm recall did not drop.
5. Verify
pytest
ruff check .
Then, against a live server, add a line to tests/smoke.sh and run it. A tool
that has never been called over real HTTP is not done.
If the tool needs a new bridge endpoint
Add the handler in whatsapp-bridge/main.go, then a thin wrapper in
whatsapp.py, then the tool in tools.py. Keep the wrapper thin: the query and
retry logic belongs in whatsapp.py, the MCP-facing shape belongs in tools.py.
Rebuild with the FTS5 tag or the bridge crash-loops:
go build -tags sqlite_fts5 ./...
