MCP tools
The fifteen tools BlueBot's MCP server offers an assistant, what each one does, the inputs it takes and the API key scope it needs.
Your assistant picks tools by their descriptions, so you rarely name one. You say "did the text to Marcus get delivered?" and it calls get_message. This page is for when you want to know exactly what it can do, choose a key's scopes, or work out why a tool answered the way it did.
Which scope each tool needs
A tool runs only when the key or sign-in has its scope. With a read-only key, the five messages:send tools and create_contact refuse, and everything else works.
| Scope | Tools |
|---|---|
messages:send | send_text, schedule_text, cancel_text, send_template, enroll_in_sequence |
messages:read | list_conversations, get_conversation, list_messages, get_message, list_templates, lookup_service |
contacts:read | search_contacts |
contacts:write | create_contact |
account:read | get_device_status, get_analytics |
No tool needs webhooks:manage.
How the tools behave
They're the API underneath. Each tool calls the same code as the REST API, so a text sent with send_text is the same message POST /v1/messages makes: the same , the same , the same . It has source: "mcp", and it fires the same webhooks.
A held text is still a sent request. When quiet hours, a daily limit or an offline Mac keeps a text from going now, the tool answers with the message queued and a hold saying why and until when. The assistant should tell you that, not try again. Sending again would only queue a second copy.
Numbers can be written any common way. Give a number however you'd say it: (555) 555-0123, 555.555.0123 or +1 555 555 0123. A number without a country code is taken as a US number. Answers always write numbers in E.164, +15555550123. An email address works for somebody on iMessage.
Conversations include what you typed by hand. get_conversation and list_messages read every text your Mac saw, including ones you sent from your iPhone or the Messages app, as long as BlueBot copies that chat.
Templates and sequences come from the dashboard. list_templates, send_template and enroll_in_sequence use the templates and sequences you made in Templates and Sequences. An assistant can't make or change them.
Lookups are best guesses. lookup_service answers from your own Messages history: if your newest chat with somebody was iMessage, they're probably on iMessage. With no history it says it doesn't know.
When a tool refuses
A refused tool call comes back as an error the assistant reads to you. The codes are the API's:
| Code | It means |
|---|---|
insufficient_scope | The key or sign-in doesn't have the scope this tool needs. |
invalid_request | An input is wrong: a number that isn't one, a time without a zone, text over 2,000 characters. |
not_found | No text, contact, template or sequence with that id on your account. |
conflict | The record is past the point where this works, such as canceling a text that already went. |
plan_lapsed | Your plan isn't active. Texts wait until it is. |
account_held | BlueBot paused sending on your account. Write to support. |
rate_limited | Too many calls in a minute. The assistant should wait and try again. |
has every code.
Every tool
send_text
Sends a text from your number now. The answer is the message with its state; a text that can’t go yet comes back queued with a hold saying why. Needs the messages:send scope.
| Input | Type | Required | What it is |
|---|---|---|---|
to | string | Yes | A phone number in any format (US assumed) or an email address on iMessage. |
text | string | Yes | The words, up to 2,000 characters. |
files | string[] | No | File ids from an upload, sent after the words. |
service | `"auto" | "imessage" | "sms"` |
metadata | object | No | String keys and values kept on the text and echoed on its webhooks. |
Try: Text Ana at +1 555 555 0123: “Running 10 minutes late, sorry!”
schedule_text
Schedules a text for a time. It stays editable and cancelable until then. Needs the messages:send scope.
| Input | Type | Required | What it is |
|---|---|---|---|
to | string | Yes | A phone number in any format (US assumed) or an email address on iMessage. |
text | string | Yes | The words. |
send_at | string | Yes | ISO 8601 time with a zone. |
metadata | object | No | String keys and values kept on the text and echoed on its webhooks. |
Try: Remind Marcus tomorrow at 9 AM that his inspection is at 11.
cancel_text
Cancels a scheduled or queued text. Needs the messages:send scope.
| Input | Type | Required | What it is |
|---|---|---|---|
id | string | Yes | The message id, msg_…. |
Try: Cancel the reminder you scheduled for Marcus.
list_conversations
Recent conversations, newest first, with the last text in each and whether it waits on you. Needs the messages:read scope.
| Input | Type | Required | What it is |
|---|---|---|---|
limit | integer | No | 1 to 50, default 20. |
waiting_on_me | boolean | No | Only conversations where the last text came in. |
Try: Who’s waiting on a reply from me?
get_conversation
The texts with one person or group, oldest to newest, including ones typed by hand on the Mac or iPhone. Needs the messages:read scope.
| Input | Type | Required | What it is |
|---|---|---|---|
person | string | No | A phone number or email. Give this or chat_id. |
chat_id | string | No | A group chat id. |
limit | integer | No | How many texts, 1 to 100, default 30. |
Try: What did Ana and I agree on last week?
list_messages
Texts in and out, filtered by person, direction, state or time. Needs the messages:read scope.
| Input | Type | Required | What it is |
|---|---|---|---|
person | string | No | A phone number or email. |
direction | `"in" | "out"` | No |
state | string | No | A message state, such as failed or unconfirmed. |
since | string | No | ISO 8601 time. |
limit | integer | No | 1 to 100, default 25. |
Try: Did any texts fail today?
get_message
One text with its state, hold and metadata. Needs the messages:read scope.
| Input | Type | Required | What it is |
|---|---|---|---|
id | string | Yes | The message id, msg_…. |
Try: Did the text to Marcus get delivered?
search_contacts
Contacts by name, number, email or tag. Needs the contacts:read scope.
| Input | Type | Required | What it is |
|---|---|---|---|
query | string | No | Words in a name, a number or an email. |
tag | string | No | Only contacts with this tag. |
limit | integer | No | 1 to 50, default 20. |
Try: Find everyone tagged “buyer”.
create_contact
Makes a contact, or updates the one with that number or email. Needs the contacts:write scope.
| Input | Type | Required | What it is |
|---|---|---|---|
handle | string | Yes | Phone number or email. |
first_name | string | No | First name. |
last_name | string | No | Last name. |
tags | string[] | No | Tags to add. |
Try: Save +1 555 555 0177 as Priya Shah, tag her “seller”.
get_device_status
Whether your Mac is online, its checks, today’s counts against your limits, and how many texts are held. Needs the account:read scope.
It takes no inputs.
Try: Is my Mac online? Why are texts waiting?
list_templates
Your saved texts and the variables each one takes. Needs the messages:read scope.
It takes no inputs.
Try: What templates do I have?
send_template
Fills a template’s variables and sends it, now or at send_at. Needs the messages:send scope.
| Input | Type | Required | What it is |
|---|---|---|---|
template_id | string | Yes | The template id, tpl_…. |
to | string | Yes | A phone number in any format (US assumed) or an email address on iMessage. |
variables | object | No | Values for the template’s {{variables}}; contact fields fill the rest. |
send_at | string | No | ISO 8601 time to send it later. |
Try: Send Ana the showing reminder for 3 PM.
enroll_in_sequence
Starts a person on a sequence of follow-ups that stops when they reply or text STOP. Needs the messages:send scope.
| Input | Type | Required | What it is |
|---|---|---|---|
sequence_id | string | Yes | The sequence id, seq_…. |
to | string | Yes | A phone number in any format (US assumed) or an email address on iMessage. |
variables | object | No | Values for the sequence’s templates. |
Try: Put Priya on the new-listing follow-up.
get_analytics
The Analytics page’s numbers for a period: sent, delivered, read, replied, failed and stopped, and your median time to reply. Needs the account:read scope.
| Input | Type | Required | What it is |
|---|---|---|---|
days | integer | No | How many days, today included, counted from midnight in your time zone: 1 to 90, default 7. |
Try: How many people replied this week, and how fast did I answer?
lookup_service
BlueBot’s best guess from your own Messages history, with its basis: history or none. Needs the messages:read scope.
| Input | Type | Required | What it is |
|---|---|---|---|
number | string | Yes | A phone number or email. |
Try: Is +1 555 555 0188 on iMessage?