MCP tools
The four Batohi MCP tools and their input schemas, generated from the live server's definitions.
MCP tools
The server registers four tools. The table and schemas below are generated from
the same MCP_TOOL_METADATA the live server registers from, so they cannot
drift from what tools/list returns.
| Tool | Description |
|---|---|
| list_recipients | List the people you have emailed, with their engagement tier (warm/cooling/cold/new) and the reasons behind it. Counts only genuine opens — proxy prefetches, self-opens, and scanners are excluded. |
| get_recipient_engagement | Get one recipient's engagement detail: messages sent, genuine opens, clicks, last activity, and their tier with reasons. Set refine:true to add an AI-suggested next step (one extra LLM call). |
| suggest_followups | Suggest who to re-engage: recipients who have gone cooling or cold, ordered coldest first, with the reason for each. Use this to decide who needs a follow-up. |
| best_send_time | Recommend the best time to send, derived from when your tracked emails actually got genuinely opened (your own history — statistics, not a guess). Times are in UTC. Returns "not enough data" until there are at least 5 genuine opens. |
| list_action_inbox | The ranked Action Inbox: every conversation with a computed verdict (state, momentum, priority, recommended next action), most urgent first, each with its conversationId for drill-down. The same list a human sees on the dashboard. |
| get_conversation_evidence | One conversation's full evidence pack: the sent message (subject, recipients, time), the engagement snapshot (opens, clicks, reply state and timing), the computed verdict with its reason codes and evidence references, recorded outcomes, and — when content capture is enabled for this account — the reply's text and the sent body. Exactly what the AI chat grounds its answers on. |
| ask_about_deals | Ask the grounded AI about your deals in natural language — "is this deal alive?", "who needs a follow-up today?", "draft my next email". Scope to one conversation with conversationId or leave it out to ask across the whole pipeline. Answers come only from tracked evidence, with citations; the answer says plainly when the evidence cannot support one. |
list_recipients
List the people you have emailed, with their engagement tier
(warm / cooling / cold / new) and the reasons behind it. Counts only
genuine opens.
Input
| Field | Type | Required | Description |
|---|---|---|---|
| tier | string | no | Optional: only recipients in this engagement tier. |
Returns { recipients: [...], count }.
get_recipient_engagement
Get one recipient's engagement detail: messages sent, genuine opens, clicks,
last activity, and tier with reasons. Set refine: true to add an AI-suggested
next step (one extra LLM call). The tier is never changed by AI.
Input
| Field | Type | Required | Description |
|---|---|---|---|
| recipient | string | yes | The recipient email address. |
| refine | boolean | no | Add an AI-suggested next step to the reasons (default false). The tier is never changed by AI. |
Returns { found, recipient, ... }, or { found: false, recipient }.
suggest_followups
Suggest who to re-engage: recipients who have gone cooling or cold, ordered coldest first, with the reason for each.
Input
| Field | Type | Required | Description |
|---|---|---|---|
| limit | integer | no | Optional max number of suggestions (default 20). |
Returns { suggestions: [...], count }.
best_send_time
Recommend the best time to send, derived from when your tracked emails actually
got genuinely opened (your own history). Times are in UTC. Returns
"not enough data" until there are at least 5 genuine opens.
Input
| Field | Type | Required | Description |
|---|
Returns { timezone: 'UTC', totalGenuineOpens, recommendation, hourHistogramUtc, dayHistogramUtc }.
Errors
Tool-level errors (bad args, unknown recipient or tier) are returned as MCP tool
results with isError: true — the model sees and can react to them, rather than
a transport-level JSON-RPC error. Anything else becomes a -32603 internal error
with no internal detail leaked.