This MCP server lets you interact with Apple iMessage through a BlueBubbles server, enabling message sending, reading, group management, and more.
Check connectivity & server info: ping, get_server_info, get_my_address
List & view chats: list_chats, get_chat, get_chat_messages, get_recent_messages, get_unread_chats, find_chats
Send messages: send_message, send_message_to_address, send_attachment, send_multipart, send_reaction, schedule_message
Edit/unsend messages: edit_message, unsend_message, delete_message
Manage group chats: create_group_chat, rename_group, set_group_icon, remove_group_icon, add_participant, remove_participant, leave_chat, delete_chat
Read/typing status: mark_chat_read, mark_chat_unread, start_typing, stop_typing
Search & retrieve messages: search_messages, get_message, get_attachment_info, download_attachment
Contact management: get_contacts, lookup_contact, find_contact, query_handles, get_handle
Check registrations: check_imessage, check_facetime
Focus & Find My: get_focus_status, find_my_devices, find_my_friends
Scheduled messages: list_scheduled_messages, get_scheduled_message, update_scheduled_message, delete_scheduled_message
Safety & access controls:
Write allowlist — restrict all write operations to a configurable list of phone numbers/emails
Freshness guard — prevent sending to stale conversations by ensuring the chat was recently read and no new messages have arrived
Private API awareness — automatically adapts available tools based on whether the BlueBubbles Private API is enabled
Contact name enrichment — resolves handles to human-readable names in responses and enables name-based searches
Compact responses — returns optimized message data by default for token efficiency, with an extended=true option for full raw fields
Provides access to iMessage via a BlueBubbles server, allowing for listing and searching chats, sending and editing messages, managing contacts, and performing group chat operations like adding or removing participants.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@bluebubbles-mcp Send a message to John saying I'll be there in 5 minutes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for BlueBubbles — access iMessage from any MCP client.
Built from scratch with no third-party MCP dependencies beyond the official mcp SDK and httpx.
Python 3.11+
A running BlueBubbles server with API access enabled
Related MCP server: mac-messages-mcp
git clone https://github.com/metaember/bluebubbles-mcp.git
cd bluebubbles-mcp
uv syncAdd to your MCP client config (e.g. Claude Code ~/.claude/settings.json):
{
"mcpServers": {
"bluebubbles": {
"command": "uv",
"args": ["--directory", "/path/to/bluebubbles-mcp", "run", "python", "-m", "bb_mcp.server"],
"env": {
"BLUEBUBBLES_URL": "https://your-bluebubbles-server",
"BLUEBUBBLES_PASSWORD": "your-server-password"
}
}
}
}By default the server can message anyone. Set BLUEBUBBLES_WRITE_ALLOWLIST to a
comma-separated list of phone numbers and/or emails to restrict every write
(send, reaction, attachment, typing, scheduling, group edits, delete/leave) to
those recipients. It is enforced server-side, so an MCP client — including one
reaching the HTTP transport — cannot bypass it.
"BLUEBUBBLES_WRITE_ALLOWLIST": "+15551234567, partner@example.com",
"BLUEBUBBLES_ALLOWLIST_REGION": "US" // optional, default region for parsing local numbersBehavior:
Unset → unrestricted (backward compatible). Set but empty ("") → deny
all, a safe failure mode.
Numbers are matched in normalized E.164 form, so (555) 123-4567 and
+15551234567 are equivalent; emails match case-insensitively.
For a group chat, every participant must be on the list or the write is blocked. A chat whose participants can't be resolved is denied (fail-closed).
Read tools are not restricted, and the message-GUID writes
(edit_message, unsend_message) aren't covered — they only act on an
already-sent message and can't reach a new recipient. A
BLUEBUBBLES_READ_ALLOWLIST may be added later.
BlueBubbles can drive Messages two ways. AppleScript works on any install with no extra setup but only sends plain texts/attachments. The Private API (requires the BlueBubbles Helper + partially disabled SIP) additionally unlocks tapbacks, edit/unsend, typing indicators, read receipts, group management, threaded replies, and SMS sending.
On startup the server reads /server/info and adapts itself to what's actually
available:
Sends use the Private API when present, and fall back to AppleScript when
not — so send_message works on a bare install instead of erroring.
Tools that require the Private API (reactions, edit/unsend, typing, read receipts, group management, iMessage/FaceTime availability checks) are hidden from the tool list when it's unavailable, so a client never sees a tool that could only fail.
Override the auto-detection with BLUEBUBBLES_PRIVATE_API:
"BLUEBUBBLES_PRIVATE_API": "auto" // default: introspect /server/info
// "true" — force-enable (assume the Private API is set up)
// "false" — force-disable (AppleScript only; hide Private API tools)If /server/info can't be read at startup, detection fails open (assumes the
Private API is available) so a transient blip doesn't hide half the toolset.
The same /server/info read also discovers the user's own iMessage address,
surfaced by the get_my_address tool. Override it if detection is wrong or you
run multiple handles:
"BLUEBUBBLES_MY_ADDRESS": "+15551234567" // or you@icloud.comMessage and chat data from BlueBubbles carries raw phone numbers and emails, not
names. To save the model from constantly cross-referencing numbers, read
responses are enriched with a contactName beside each handle, and
find_contact / find_chats let it reach people by name instead of number.
Resolution is lazy and cached per session: a response's addresses are looked up
in a single batched /contact/query the first time they're seen, then reused.
Disable it (for leaner responses or if your contact DB is slow) with:
"BLUEBUBBLES_RESOLVE_NAMES": "false" // default: enabledfind_contact / find_chats still work when this is off — they're explicit.
An agent can reply to a conversation against a stale snapshot — it read the thread
a while ago, a new message arrived in the gap, and it answers without seeing it.
The freshness guard enforces, server-side and per agent, that a send into a chat
only goes through if that agent read the chat within the last hour and nothing
new has arrived since. (A consequence: you must read an existing chat before
sending into it — good hygiene for replies. Starting a brand-new conversation via
create_chat is unaffected; it's for first contact only and, with the guard on,
refuses to reach an existing chat — use send_message for those.)
How it works. The guard keeps a per-agent watermark — the newest message each
agent has seen in each chat (optimistic concurrency, like an ETag on the thread):
Reading a chat with get_chat_messages records the watermark. Only that tool
records — a scan like get_unread_chats doesn't — so to reply you must
deliberately open the actual thread.
Before a send, the server re-checks the chat's live newest message. If anything (from anyone — the other person, you on another device, or another agent) arrived since your watermark, or your read is older than the TTL, the send is blocked with a note to re-read and re-plan.
Your own send advances your watermark, so sending doesn't block your next send.
See docs/freshness-guard.md for the full design.
On by default. Disable with BLUEBUBBLES_FRESHNESS=off. Tuning:
"BLUEBUBBLES_FRESHNESS": "off", // default: on
"BLUEBUBBLES_FRESHNESS_IDENTITY": "session", // how agents are told apart (default)
"BLUEBUBBLES_WATERMARK_TTL_SECONDS": "3600", // how long a read stays "fresh" (default 1h)
"BLUEBUBBLES_WATERMARK_MAX_AGENTS": "10000" // memory backstop (default 10000)The freshness check is per agent, so it needs to tell agents apart.
BLUEBUBBLES_FRESHNESS_IDENTITY selects how:
session (default): use the MCP transport session — automatic and
zero-config for stdio (one agent) and direct HTTP (one session per
connecting client). Over HTTP this relies on stateful sessions (FastMCP's
default); the server refuses to start if you combine session-identity
freshness with stateless HTTP, since every send would be blocked.
meta: identify agents by a per-agent agentId the caller stamps into
request _meta. Required only behind a pooling proxy/airlock, where every
agent shares one transport session so session can't distinguish them. See
docs/freshness-guard.md for the airlock contract.
Message reads return a compact projection by default — the fields an
assistant needs (guid, text, handle + contactName, isFromMe,
timestamps, attachment names, reaction/reply linkage) instead of the full raw
BlueBubbles objects, which cuts token usage substantially. Pass extended=true
on any read tool to get the complete raw fields.
Message reads (get_chat_messages, search_messages, get_recent_messages)
also accept from_address to filter by who sent each message — pass a phone
number / email, or "me" for the user's own messages. Filtering is by true
sender (the user when isFromMe, otherwise the message's handle), so it's
correct in both 1:1 and group chats.
Tool | Description | Annotations |
| Check server connectivity | read-only |
| Server info and health | read-only |
| The user's own iMessage address (to identify their own messages) | read-only |
| List conversations by recent activity | read-only |
| Chat details with participants | read-only |
| Messages from a chat | read-only |
| Search by text, chat, time range | read-only |
| Single message by GUID | read-only |
| All contacts | read-only |
| Look up name by phone/email | read-only |
| Find contacts by name (phone/email unknown) | read-only |
| Find chats involving a contact by name | read-only |
| Check iMessage registration | read-only |
| Check FaceTime registration | read-only |
| List/search known handles | read-only |
| Get a handle by address | read-only |
| Contact's Focus / Do Not Disturb status | read-only |
| Find My — your devices' locations | read-only |
| Find My — friends' locations | read-only |
| List future messages | read-only |
| Get one scheduled message by ID | read-only |
| Messages from last N minutes across all chats | read-only |
| Chats with unread messages + their latest messages | read-only |
| Attachment metadata | read-only |
| Download attachment as base64 | read-only |
| Download a group chat's icon | read-only |
| Send read receipt | idempotent, open-world |
| Mark chat unread (local) | idempotent |
| Rename a group chat | idempotent |
| Set a group chat's icon | idempotent |
| Show typing indicator | open-world |
| Stop typing indicator | open-world |
| Send to an existing chat (1:1 or group) | open-world |
| Start a new 1:1 conversation by phone/email | open-world |
| Create a group chat + first message | open-world |
| Send a file attachment | open-world |
| Send text + attachments as one message | open-world |
| Tapback reaction | open-world |
| Edit a sent message | open-world |
| Schedule a future message | open-world |
| Update a scheduled message | open-world |
| Add to group chat | open-world |
| Retract a message | destructive, open-world |
| Remove from group chat | destructive, open-world |
| Leave a group chat | destructive, open-world |
| Remove a group chat's icon | destructive, open-world |
| Delete a single message | destructive, open-world |
| Delete a conversation | destructive, open-world |
| Cancel scheduled message | destructive, open-world |
The server speaks stdio by default. Set MCP_TRANSPORT=streamable-http to serve
over Streamable HTTP instead, so any
HTTP-capable MCP client can connect at http://<host>:8000/mcp. The Docker image
sets this for you.
docker build -t bluebubbles-mcp .
docker run --rm -e BLUEBUBBLES_URL -e BLUEBUBBLES_PASSWORD -p 8000:8000 bluebubbles-mcpAs a Compose service — credentials live in this container's own environment (an
env_file or Docker secrets), so they stay isolated to this tool:
services:
bluebubbles-mcp:
build: .
environment:
BLUEBUBBLES_URL: ${BLUEBUBBLES_URL}
BLUEBUBBLES_PASSWORD: ${BLUEBUBBLES_PASSWORD}
restart: unless-stoppedNotes:
The HTTP endpoint is unauthenticated, so don't expose it publicly — keep it on a
private/internal network (and drop the published ports: if a co-located client
reaches it over the Compose network).
BLUEBUBBLES_URL must be reachable from inside the container — use a
hostname/IP the container can resolve (e.g. the BlueBubbles host's LAN address or
host.docker.internal), not localhost.
MIT
Add a participant to a group chat.
Args: chat_guid: The group chat GUID. address: Phone number or email of the person to add.
| Name | Required | Description | Default |
|---|---|---|---|
| chat_guid | Yes | ||
| address | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false and destructiveHint=false, indicating mutation. The description adds that it modifies a chat, but does not disclose requirements like being a chat member or permissions. Adequate given annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences with no filler. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool with an output schema (not shown), the description covers the basic action and parameters. Lacks constraints like precondition that user must be in chat, but sufficient for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description explains each parameter's purpose ('The group chat GUID' and 'Phone number or email'), adding value over just titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('add a participant') and the resource ('group chat'). It distinguishes from sibling tools like 'remove_participant'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'send_message' or 'send_message_to_address'. The description simply states the purpose without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check if a phone number or email is registered for FaceTime.
Args: address: Phone number or email to check.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, idempotentHint. Description adds no further behavioral context beyond stating the action 'check', which is consistent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise, two short sentences with no wasted words. Front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple check tool, the description covers the core functionality. Missing explicit mention of return value, but output schema likely fills that gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description clarifies that 'address' is a phone number or email, adding semantic meaning beyond the schema's type 'string'. With 0% schema description coverage, this compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'check' and the resource 'FaceTime registration', distinguishing it from sibling 'check_imessage' which likely checks iMessage registration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like check_imessage, or any context-specific conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check if a phone number or email is registered for iMessage.
Args: address: Phone number or email to check.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description is consistent but adds no additional behavioral details beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence plus a parameter line. No superfluous content; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with an output schema, the description adequately explains its purpose and parameter format. No additional context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds critical meaning by specifying that the 'address' parameter accepts a phone number or email. This compensates for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks if a phone number or email is registered for iMessage. It is specific and distinguishes from sibling tools like check_facetime.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives like check_facetime. Usage is implied by the name, but no exclusions or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an entire chat conversation. This is irreversible.
Args: chat_guid: The chat GUID to delete.
| Name | Required | Description | Default |
|---|---|---|---|
| chat_guid | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true. The description adds 'This is irreversible' which reinforces the destructive nature. However, no additional behavioral traits (e.g., effects on participants, message deletion) are disclosed, so the description adds only modest value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the main purpose, followed by an Args section. It contains no unnecessary text. Slightly more structured formatting could be beneficial, but it remains concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, destructive, with output schema present), the description adequately covers the purpose, irreversibility, and parameter meaning. However, it could mention that the chat must exist or what happens to associated data, but overall it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by explaining chat_guid as 'The chat GUID to delete'. This provides essential meaning for the single parameter, making up for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Delete an entire chat conversation' with the resource 'chat conversation'. It also notes irreversibility. This distinguishes it from sibling tools like remove_participant (removes a person) and leave_chat (exits chat without deletion).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like leave_chat or remove_participant. The description does not mention prerequisites, required permissions, or comparison with similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a scheduled message.
Args: schedule_id: The ID of the scheduled message to cancel.
| Name | Required | Description | Default |
|---|---|---|---|
| schedule_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already communicate destructive and non-idempotent nature. Description adds no further behavioral context beyond confirming deletion, which is acceptable but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise with the action upfront, but includes an unnecessary Args block that repeats the schema. Could be more streamlined.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists but description omits crucial context like irreversibility, prerequisites (message must be scheduled), and relationship to siblings like schedule_message or unsend_message.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but description explains schedule_id as 'The ID of the scheduled message to cancel.' This adds meaningful context beyond the schema's type and title.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Delete a scheduled message.' with a precise verb and resource, distinguishing it from siblings like schedule_message, unsend_message, and list_scheduled_messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like unsend_message for sent messages or schedule_message for scheduling. Agent is left to infer context from tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download an attachment and return it as base64-encoded data.
Args: attachment_guid: The attachment GUID.
| Name | Required | Description | Default |
|---|---|---|---|
| attachment_guid | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description does not add behavioral context beyond the docstring format, which is consistent but not enriching.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise and front-loaded: the first sentence explains purpose and output. No redundant words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple download tool with output schema present, the description is complete. It explains the action and return format, no gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter attachment_guid is explained in the docstring as 'The attachment GUID,' adding meaning beyond the schema's title and type. Schema description coverage is 0%, so description compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Download an attachment and return it as base64-encoded data,' identifying the verb (download), resource (attachment), and output format. It distinguishes from siblings like get_attachment_info and send_attachment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives like get_attachment_info. The context is implied (use to get raw attachment data) but not stated, leaving agents to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit a previously sent message.
Args: message_guid: GUID of the message to edit. new_text: The new message text.
| Name | Required | Description | Default |
|---|---|---|---|
| message_guid | Yes | ||
| new_text | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate write operation, but description adds no behavioral details beyond parameter names. No mention of effects on other participants or conditions like edit window.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise one-line summary with parameter definitions. Front-loaded and no extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Sufficient for a simple edit tool but lacks details on error responses, access permissions, or time restrictions. Output schema presence mitigates some gaps but description incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Minimal clarification beyond schema (e.g., 'GUID of message' and 'new text'). No format examples, length limits, or behavior consequences given 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Edit' and specific resource 'previously sent message'. Distinct from siblings like send_message or unsend_message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this vs alternatives (e.g., unsend and resend). No mention of constraints like time limits or sender requirements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get metadata for an attachment (filename, mime type, size, etc.).
Args: attachment_guid: The attachment GUID.
| Name | Required | Description | Default |
|---|---|---|---|
| attachment_guid | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds no additional behavioral context beyond that. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is very short and front-loaded, but every sentence is necessary. Could be slightly enhanced with usage hints without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 1-parameter tool with output schema, the description is minimally complete. It lacks context on error cases (e.g., invalid guid), expected behavior, or return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%. The description only restates the parameter name and type ('attachment_guid: The attachment GUID'), adding no semantics beyond what the schema title provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it gets metadata for an attachment, listing examples like filename, mime type, size. The verb 'Get' and resource 'attachment info' are specific, but no differentiation from sibling 'download_attachment' is provided.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like download_attachment or get_message. Only states what it does, not when it's appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details for a specific chat, including participants.
Args: chat_guid: The chat GUID (e.g. 'iMessage;-;+15551234567' or 'iMessage;+;chat123').
| Name | Required | Description | Default |
|---|---|---|---|
| chat_guid | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, and idempotentHint, so the description need not repeat them. It adds that details include participants, which is consistent with the read-only behavior. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one short sentence for purpose and one line for the parameter example. No superfluous text, perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single parameter, return details) and the existence of an output schema, the description adequately covers what the agent needs to know. It mentions 'participants' as a key return field, which is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description provides a concrete example for the parameter (e.g., 'iMessage;-;+15551234567'), adding significant meaning beyond the bare schema. This compensates well for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves details for a specific chat, including participants. It uses a specific verb ('get') and resource ('chat'), distinguishing it from sibling tools like list_chats or get_chat_messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when needing details of a single chat but does not explicitly state when to use it versus alternatives (e.g., list_chats, get_chat_messages). No exclusions or recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get messages from a specific chat.
Args: chat_guid: The chat GUID. limit: Max messages to return (default 25). offset: Pagination offset. sort: 'ASC' or 'DESC' (default DESC = newest first). after: Only messages after this epoch-ms timestamp. before: Only messages before this epoch-ms timestamp.
| Name | Required | Description | Default |
|---|---|---|---|
| chat_guid | Yes | ||
| limit | No | ||
| offset | No | ||
| sort | No | DESC | |
| after | No | ||
| before | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds behavioral details like pagination (limit, offset), sorting (ASC/DESC), and timestamp filters (after/before), which are not in annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a clear purpose statement followed by parameter explanations. It is front-loaded and structured. Minor redundancy could be trimmed, but overall efficient for 6 parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and annotations covering safety, the description sufficiently covers all parameter semantics, filtering, and pagination. No gaps remain for a read-only retrieval tool with this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must fully explain parameters. It does so: chat_guid (required), limit (max messages, default 25), offset (pagination), sort (ASC/DESC, default DESC newest first), after and before (epoch-ms timestamps). This adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get messages from a specific chat', specifying the verb and resource. It distinguishes itself from siblings like get_recent_messages (which likely returns messages across chats) and search_messages by focusing on a single chat with filtering options.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains parameters and their defaults (e.g., sort defaults to DESC, limit defaults to 25) but does not explicitly guide when to use this tool over siblings like get_recent_messages or search_messages. Usage is implied but lacks explicit when-to-use or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all contacts from the server.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, covering safety profile. The description adds no behavioral details beyond 'from the server', which is minimal and generic.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no fluff, perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, output schema present, annotations covering risk), the brief description is sufficient. It could mention what 'all contacts' means (e.g., scope), but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has zero parameters (100% schema coverage trivially). With no params, the description carries no parameter burden and is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get all contacts from the server' clearly states a specific verb ('Get') and resource ('all contacts'), distinguishing it from sibling tools like 'lookup_contact' which suggests a single contact lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks any guidance on when to use this tool vs alternatives (e.g., 'lookup_contact' for single contacts, 'get_unread_chats' for chats). No context about prerequisites or scenarios is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single message by its GUID, including chat and attachment info.
Args: message_guid: The message GUID.
| Name | Required | Description | Default |
|---|---|---|---|
| message_guid | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds that it includes 'chat and attachment info', which is beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single-line summary plus minimal Args section. No redundant sentences or filler; every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main purpose and parameter. With output schema present, return values are documented. Could mention error handling (e.g., message not found), but adequate for a simple retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%. Description merely restates 'The message GUID' for the parameter, adding little beyond the schema's title 'Message Guid'. Fails to compensate for low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get a single message by its GUID', providing a specific verb and resource. It distinguishes from siblings like get_chat_messages (multiple messages) and search_messages (search-based).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives mentioned. Implies usage for retrieving a specific known message via GUID, but lacks guidance on when to prefer this over get_chat_messages or search_messages.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get recent messages across all chats within a time window.
Args: minutes: How far back to look (default 60 minutes). limit: Max messages to return (default 50).
| Name | Required | Description | Default |
|---|---|---|---|
| minutes | No | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds no additional behavioral traits beyond the time window scope. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single line for purpose then two lines for parameters. No fluff, front-loaded with the key action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema existence and low parameter count (2), the description covers the purpose and parameters adequately. It could mention ordering or pagination, but the output schema likely covers return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds clear semantics: 'minutes: How far back to look' and 'limit: Max messages to return' with defaults. This compensates well for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get recent messages across all chats within a time window,' specifying a specific verb and resource, and distinguishes from siblings like get_chat_messages (specific chat) or get_message (single message).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the parameters and defaults but does not explicitly guide when to use this tool over alternatives like get_chat_messages or search_messages. Usage is implied but not directly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get BlueBubbles server info and health status.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly and idempotent. Description adds 'health status' context but doesn't disclose additional behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with zero waste, front-loaded with key info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool is simple with no parameters and output schema present. Description fully suffices for successful agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters; schema coverage is 100%, so description has nothing to add. Baseline 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource ('Get BlueBubbles server info and health status'). Distinct from sibling tools that focus on messages, chats, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives, but given it's the only server info tool, the purpose is self-explanatory.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all chats with unread messages, including their latest messages.
Args: message_limit: Number of recent messages to include per unread chat (default 5).
| Name | Required | Description | Default |
|---|---|---|---|
| message_limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark as readOnly, idempotent, non-destructive. Description adds that it returns latest messages with parameter limit, but no further behavioral traits beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states purpose, second describes parameter. No extraneous text, front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists and annotations cover safety, description is complete: explains what tool returns and its sole parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but description explains message_limit parameter: 'Number of recent messages to include per unread chat (default 5).' Adds meaning not in schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get all chats with unread messages, including their latest messages.' Verb 'get' and resource specified, distinguishable from siblings like list_chats or get_chat.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicit usage guidance from name and description, but no explicit when-to-use or when-not-to-use compared to many sibling tools. Parameter description is helpful but not usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Leave a group chat.
Args: chat_guid: The group chat GUID to leave.
| Name | Required | Description | Default |
|---|---|---|---|
| chat_guid | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint:true, so the description's mention of 'leave' is consistent. However, no extra details are added about irreversibility, permissions, or side effects. The description adds marginal value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences plus args), which is concise, but it omits important context that would justify its brevity. It could be more informative without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but the description lacks any mention of what happens after leaving (e.g., confirmation, effects on messages). The output schema exists but is not referenced. The description feels incomplete for full agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description only restates the parameter name and type from the schema. It adds no additional meaning about format, constraints, or how to obtain the GUID.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'leave' and the resource 'group chat', making the purpose immediately obvious. It distinguishes from sibling tools like delete_chat or remove_participant.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., delete_chat or remove_participant). The description does not provide any contextual cues for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List iMessage conversations, sorted by most recent activity.
Args: limit: Max number of chats to return (default 25). offset: Pagination offset.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by stating the sorting behavior (most recent activity). No other behavioral traits are needed for a simple list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one sentence for purpose and two bullet-like parameter explanations. Every sentence adds value with no redundancy. Front-loaded with the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with two optional parameters, existing output schema, and informative annotations, the description covers sorting, pagination, and defaults. It doesn't mention if only iMessage chats are returned, but that is implicit in the tool name. Sufficient for usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description explains limit as 'Max number of chats to return (default 25)' and offset as 'Pagination offset', adding meaning beyond the schema's default values and types. Could clarify offset semantics further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'List iMessage conversations' with a clear verb and resource, and specifies sorting by most recent activity, distinguishing it from siblings like get_chat or get_recent_messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like get_unread_chats or search_messages. Usage is implied by the function name and context, but no exclusions or scenarios are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all scheduled (future) messages.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds minimal behavioral context beyond clarifying 'future' messages, but does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single short sentence, front-loaded, no wasted words. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, rich annotations, and an output schema, the description is minimally sufficient. It clearly states the tool's function without needing additional detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has no parameters, so schema coverage is 100%. Description does not need to add parameter details; baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'List all scheduled (future) messages,' using a specific verb and resource. It distinguishes from sibling tools like delete_scheduled_message and schedule_message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description implies its use case but does not mention exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up contacts by phone numbers or email addresses.
Args: addresses: List of phone numbers or emails to look up.
| Name | Required | Description | Default |
|---|---|---|---|
| addresses | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, non-destructive, idempotent behavior. The description adds no further behavioral traits beyond the input format, so it meets the baseline but adds no extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear main sentence, followed by an args list. It is mostly concise, though the args list could be condensed without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description does not need to detail return values. However, it omits what happens when no contact is found or when multiple matches occur, which would be useful context for a lookup tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the only parameter, 'addresses', by clarifying it is a list of phone numbers or emails. This is valuable since the schema description coverage is 0%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool looks up contacts by phone numbers or email addresses, using a specific verb and resource. It distinguishes itself from sibling tools like get_contacts and send_message_to_address.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not indicate when to use this tool versus alternatives such as get_contacts or search_messages, which is important given the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a chat as read (sends read receipt visible to the other person).
Args: chat_guid: The chat GUID.
| Name | Required | Description | Default |
|---|---|---|---|
| chat_guid | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds behavioral detail beyond annotations: 'sends read receipt visible to the other person'. Annotations idempotentHint=true supports this. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Could be slightly more structured, but overall concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists and tool is simple, description is adequate but minimal. Could mention idempotency (already in annotations) or expected behavior if chat already read.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. However, it only restates the parameter name as 'The chat GUID', adding no extra semantics like format or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action 'mark a chat as read' and the resource. Distinguishes from sibling 'mark_chat_unread' by specifying it sends a read receipt.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies usage (when you want to mark chat as read), but no explicit when-not-to-use or comparison with alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a chat as unread.
Args: chat_guid: The chat GUID.
| Name | Required | Description | Default |
|---|---|---|---|
| chat_guid | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true, which is not elaborated in the description. No additional behavioral traits disclosed beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is overly brief, missing essential details. While short, it sacrifices completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description fails to mention return values or side effects (e.g., what happens if the chat is already unread). Incomplete for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description merely repeats 'the chat GUID' from the schema title, adding no semantic value beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Mark a chat as unread' clearly states the verb and resource. However, it does not differentiate from the sibling 'mark_chat_read', which is obvious but could be improved by adding context like 'that is currently read'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs. alternatives (e.g., 'mark_chat_read'). No mention of prerequisites or conditions for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ping the BlueBubbles server to check connectivity.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, etc. Description adds minimal extra behavior context ('check connectivity'), which is consistent. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded, zero waste. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, output schema exists, and annotations cover safety, the description is fully complete for a simple ping/health-check tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline is 4. Description does not need to add parameter info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'ping' and resource 'BlueBubbles server' with explicit purpose 'check connectivity'. Distinguishes from all sibling tools which are more complex operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or alternatives, but purpose is self-evident as a connectivity check, which is distinct from all sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a participant from a group chat.
Args: chat_guid: The group chat GUID. address: Phone number or email of the person to remove.
| Name | Required | Description | Default |
|---|---|---|---|
| chat_guid | Yes | ||
| address | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates a destructive action ('Remove'), which aligns with the destructiveHint: true annotation. However, it does not add behavioral details beyond what annotations already provide, such as side effects or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence for purpose followed by parameter explanations. No unnecessary words, and the main action is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple removal tool with an output schema present, the description covers the essential information: what it does and the required parameters. It lacks details on return behavior, but the output schema likely handles that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to both parameters: 'chat_guid' is identified as the group chat GUID, and 'address' is specified as phone number or email. The input schema has no descriptions (0% coverage), so the description compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Remove a participant') and the target resource ('from a group chat'). This distinguishes it from the sibling tool 'add_participant' and other chat-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool or provide exclusions. While the purpose is clear, there is no guidance on prerequisites (e.g., being a group admin) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename a group chat.
Args: chat_guid: The group chat GUID. name: New display name for the group.
| Name | Required | Description | Default |
|---|---|---|---|
| chat_guid | Yes | ||
| name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it is not read-only, not destructive, and idempotent. The description adds minimal behavioral context beyond the parameter names, but does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one title sentence followed by parameter definitions. No wasted words, clearly structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers the purpose and parameters. Output schema exists, so return values are not needed. Could mention constraints on name length or GUID format, but adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description compensates by explaining both parameters (GUID and new name). Adds meaning beyond type-only schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Rename a group chat,' using a specific verb and resource. Among siblings, no other tool renames, so it distinguishes itself effectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like delete_chat or edit_message. No prerequisites or exclusions provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Schedule a message to be sent at a future time.
Args: chat_guid: The chat GUID to send to. message: The message text. scheduled_for: When to send, as epoch milliseconds.
| Name | Required | Description | Default |
|---|---|---|---|
| chat_guid | Yes | ||
| message | Yes | ||
| scheduled_for | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is not read-only, not destructive, not idempotent, and open world. The description adds no further behavioral traits beyond the act of scheduling, which is already clear. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence for purpose and a bullet-like list for parameters. Every sentence serves a purpose with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully explains purpose and all parameters. It could mention the existence of 'delete_scheduled_message' for cancellation, but given the output schema exists and the tool is simple, it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the input schema by defining each parameter: 'chat_guid: The chat GUID to send to', 'message: The message text', 'scheduled_for: When to send, as epoch milliseconds'. This fully compensates for the schema's lack of property descriptions (0% description coverage).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Schedule a message to be sent at a future time,' which is a specific verb+resource pair. It implicitly distinguishes from the sibling 'send_message' (which sends immediately) and 'delete_scheduled_message'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives like 'send_message' or 'delete_scheduled_message'. The usage context is implied but not contrasted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search messages by text content and/or filter by chat and time range.
Args: query: Text to search for in message bodies. chat_guid: Limit search to a specific chat. limit: Max results (default 25). offset: Pagination offset. after: Only messages after this epoch-ms timestamp. before: Only messages before this epoch-ms timestamp.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | ||
| chat_guid | No | ||
| limit | No | ||
| offset | No | ||
| after | No | ||
| before | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds filtering scope but no additional behavioral traits (e.g., performance, pagination behavior). Adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One-sentence purpose followed by a clean bullet list of args. No fluff, front-loaded, every sentence earns its place. Efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all parameters and search scope. Output schema exists, so return details are not required. Could mention ordering or result format, but sufficient for typical use given complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but description provides one-liners for all 6 parameters, including units (epoch-ms), defaults (e.g., limit 25), and purpose (e.g., 'search for in message bodies'). Adds significant value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'search' with resource 'messages'; description specifies filtering by text, chat, and time range. Distinguishes from siblings like get_chat_messages (no text search) and get_message (single message).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States when to use: search by text content or filters. Does not explicitly exclude cases or mention alternatives, but the purpose is clear and siblings provide context. No misleading guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a file attachment to a chat.
Args: chat_guid: The chat GUID to send to. data_base64: The file contents as a base64-encoded string. filename: The filename (e.g. 'photo.jpg'). mime_type: MIME type (e.g. 'image/jpeg'). Defaults to 'application/octet-stream'.
| Name | Required | Description | Default |
|---|---|---|---|
| chat_guid | Yes | ||
| data_base64 | Yes | ||
| filename | Yes | ||
| mime_type | No | application/octet-stream |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only and non-destructive. The description adds that it sends to a chat with base64 data, which is consistent but does not disclose additional behavioral traits (e.g., impact on chat, idempotency). It provides no new behavioral insights beyond what annotations offer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a single sentence stating purpose followed by a bullet-list of parameters. Every sentence is useful, no fluff. It is front-loaded with the main action and well-structured for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 params, output schema exists), the description covers all parameters and the primary action. It does not detail return values (handled by output schema) or error scenarios, but is sufficient for basic invocation. Could be improved with prerequisites (e.g., 'requires an active chat' or 'use with valid chat_guid').
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It clearly explains each parameter (chat_guid, data_base64, filename, mime_type with default), adding meaning beyond the schema's titles and defaults. For example, it clarifies that data_base64 is the file contents and mime_type defaults to 'application/octet-stream'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Send a file attachment to a chat', specifying the verb (send) and resource (file attachment). This distinguishes it from sibling tools like send_message (text) and download_attachment (receive).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly guide when to use this tool vs alternatives (e.g., send_message for text). It implies usage for file attachments but lacks context like 'use for binary content' or 'not for text messages'. No exclusions or alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a text message to an existing chat.
Args: chat_guid: The chat GUID to send to. message: The message text. reply_to_guid: Optional message GUID to reply to (creates a thread).
| Name | Required | Description | Default |
|---|---|---|---|
| chat_guid | Yes | ||
| message | Yes | ||
| reply_to_guid | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the write nature is clear. The description adds the threading capability via reply_to_guid, but does not disclose additional behavioral details like permissions or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences introducing the tool, followed by a clear parameter list. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description does not need to explain return values. It covers the core functionality and parameters adequately. However, given sibling tools, additional context about when to use this over alternatives would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description adds meaning to each parameter: 'chat_guid: The chat GUID to send to,' 'message: The message text,' 'reply_to_guid: Optional message GUID to reply to (creates a thread).' This goes beyond the schema names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Send a text message to an existing chat,' identifying the verb (send) and resource (text message). This distinguishes it from siblings like 'send_attachment' or 'send_message_to_address'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for sending text messages to chats and mentions optional threading. However, it does not explicitly state when to use this tool versus alternatives like 'send_attachment' or 'send_message_to_address'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a message to a phone number or email, creating a new chat if needed.
Args: address: Phone number (e.g. '+15551234567') or email address. message: The message text. service: 'iMessage' or 'SMS' (default iMessage).
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | ||
| message | Yes | ||
| service | No | iMessage |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context about creating new chats and service defaults beyond annotations, but does not disclose potential risks like costs or address validation. The openWorldHint already covers external interaction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise two-paragraph format with clear arg list. Purpose is front-loaded, no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, parameter details, and behavioral context for a simple tool with three params and an output schema. No significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description provides meaningful explanations for each parameter (e.g., address format, service options) beyond the schema, compensating for 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool sends a message to a phone number or email and creates a new chat if needed. This distinguishes it from sibling tools like 'send_message' which likely require an existing chat.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies when to use by describing the behavior of creating a new chat, but does not explicitly state when not to use or contrast with alternatives like 'send_message'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a tapback reaction to a message.
Args: chat_guid: The chat GUID containing the message. message_guid: The GUID of the message to react to. reaction: One of: love, like, dislike, laugh, emphasize, question. Prefix with '-' to remove (e.g. '-love').
| Name | Required | Description | Default |
|---|---|---|---|
| chat_guid | Yes | ||
| message_guid | Yes | ||
| reaction | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-readOnly. Description adds removal prefix feature but does not mention side effects, rate limits, or failure conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and includes parameter docs in a structured Args format. Could be slightly more front-loaded but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Mostly complete for a simple tool with 3 parameters and output schema present. Lacks error handling info but covers input adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description fully explains each parameter: chat_guid, message_guid, and reaction with valid values and prefix for removal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Send a tapback reaction to a message.' Uses specific verb and resource, distinguishes from siblings like send_message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternative comparison. Usage is implied by the action but lacks context like prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show a typing indicator in a chat (visible to the other person).
Args: chat_guid: The chat GUID.
| Name | Required | Description | Default |
|---|---|---|---|
| chat_guid | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is not read-only, not destructive, and not idempotent. The description adds that the indicator is visible to the other person, which is helpful. However, it omits details like duration, rate limits, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using two sentences to convey the purpose and parameter. It is front-loaded and avoids any unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (one parameter, simple action) and presence of an output schema, the description covers the essential purpose. However, it could mention potential failure cases or the need to call 'stop_typing' later for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate. It only restates the parameter name ('chat_guid: The chat GUID'), adding very little meaning beyond the input schema's title. No format, constraints, or examples are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to show a typing indicator in a chat. It uses a specific verb-resource pair ('Show a typing indicator') and is easily distinguishable from the sibling tool 'stop_typing'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'stop_typing'. There is no mention of prerequisites or contexts where starting a typing indicator is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop the typing indicator in a chat.
Args: chat_guid: The chat GUID.
| Name | Required | Description | Default |
|---|---|---|---|
| chat_guid | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate non-read-only and non-destructive. Description adds no extra behavioral context, such as whether it is safe to call multiple times or if it has side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very short and front-loaded with purpose. Could benefit from a structured Args line, but still concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple mutation tool, but fails to explain the effect on the chat indicator or expected output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description defines chat_guid as 'The chat GUID.' This adds basic meaning but lacks format or example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it stops the typing indicator in a chat. Distinguishes from sibling 'start_typing', but could be more specific about context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use, prerequisites, or alternatives. Does not mention complementary relationship with 'start_typing'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unsend (retract) a previously sent message.
Args: message_guid: GUID of the message to unsend.
| Name | Required | Description | Default |
|---|---|---|---|
| message_guid | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint=true and openWorldHint=true. The description adds minimal context (only 'previously sent'), not disclosing potential constraints like time limits or failure conditions, so it fails to add significant value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the purpose, followed by parameter documentation. It is efficient but could be slightly more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description does not mention return values or behavior (e.g., success/failure conditions, time constraints). It is incomplete for a destructive action, leaving important gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description includes a parameter doc for message_guid ('GUID of the message to unsend'), which adds meaning beyond the schema's type and title, compensating for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Unsend (retract) a previously sent message,' providing a specific verb (unsend/retract) and resource (previously sent message), distinguishing it from siblings like delete_chat or edit_message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives or when not to use it. The description lacks explicit context for usage, such as prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0add_participantcheck_facetimecheck_imessagedelete_chatdelete_scheduled_messagedownload_attachmentedit_messageget_attachment_infoget_chatget_chat_messagesget_contactsget_messageget_recent_messagesget_server_infoget_unread_chatsleave_chatlist_chatslist_scheduled_messageslookup_contactmark_chat_readmark_chat_unreadpingremove_participantrename_groupschedule_messagesearch_messagessend_attachmentsend_messagesend_message_to_addresssend_reactionstart_typingstop_typingunsend_messageEach tool has a clear, distinct purpose. Sending tools are differentiated by target (existing chat vs. new address), type (text, attachment, reaction), and timing (immediate vs. scheduled). No overlapping functionality.
Tool names consistently follow a verb_noun pattern (e.g., send_message, get_chat, delete_chat). Minor variations like 'check_facetime' and 'mark_chat_unread' are still consistent in structure.
33 tools is above average but appropriate for a comprehensive iMessage server covering messaging, attachments, reactions, scheduling, participants, contacts, and typing indicators. Each tool serves a unique function.
The tool set covers the full lifecycle of messaging: send, receive, edit, unsend, schedule, react, manage participants, handle attachments, search, and check user availability. No obvious gaps for core iMessage operations.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP connector for iMessage & Contacts via a local Mac agent + Vercel relay
WhatsApp (Web + Business API), SMS, contacts, and call records via 2Chat's MCP server.
Drive WhatsApp from any MCP client: pair devices, send text and media, manage contacts and groups.
MCP connector that lets ChatGPT list, search, and run your Apple Shortcuts via a local Mac agent
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/metaember/bluebubbles-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
