mcp tool descriptions are agent invocation protocols, not blurbs

Because the dangerous part of sending a message isn't the typing, it's sending it to the wrong chat. The Swift handler `handleSendMessage` is a few lines of accessibility calls. The description is 31 words because those words are the contract that prevents an agent from invoking the tool with the wrong contact in focus. The description names the three sibling tools that must have run first: whatsapp_search, whatsapp_open_chat, and whatsapp_get_active_chat. Without that prose, an agent that has just listed chats and seen 'Mom' on screen would reasonably conclude that calling whatsapp_send_message would send to Mom. It would be wrong, because the active chat is whichever one the user last clicked, not whichever one the model last saw mentioned. The description encodes that invariant.

Because in practice, the agent doesn't 'just remember'. Between whatsapp_open_chat and whatsapp_send_message, several other tool calls might happen: a list_chats refresh, a notification dialog the user clicked through, a scroll. The native WhatsApp Catalyst app's active-chat state is the source of truth, not the model's working memory. whatsapp_get_active_chat returns that ground-truth value, and its description ('Use this to verify which chat is open before sending a message') tells the model when to call it. It's a tool that exists to be a checkpoint in the protocol, and its description is what makes it act like one.

It could, but the Swift implementation chose the opposite trade-off, and the description is where you can read the reasoning. The composed tool would have to swallow search ambiguity, scroll behaviour, and verification inside one call, which means errors come back as 'tool failed' with no way for the model to recover gracefully. Splitting it into four narrow tools, each with a description that names the next, lets the model reason between steps. If whatsapp_open_chat returns 'Mom' instead of 'Mum (work)', the model can call whatsapp_search again with a refined query. The description on whatsapp_open_chat anticipates this exact failure: 'verify this matches your intended contact'.

It is not in the MCP specification. The spec defines that a tool MUST have a description string and that the string is shown to the model, but it doesn't prescribe what to put in it. The MCP servers that work well in practice tend to name siblings by exact name, because hosts such as Claude Code expose the full list to the model on every turn, and the model is much more likely to pick a tool whose description was just referenced by the previous tool's description. The cost is that renaming a tool now means searching every other description for the old name. The whatsapp-mcp-macos source has 'whatsapp_search' hardcoded in three other tool descriptions, so renaming it would silently break the protocol if any reference is missed.

The host calls tools/list once per session over the stdio transport. The server returns an array of tool objects, each with name, description, and inputSchema. The host then injects all of that into the model's system prompt for the duration of the session. So when whatsapp_send_message's description says 'Use whatsapp_search + whatsapp_open_chat + whatsapp_get_active_chat to verify the right chat first', the model literally sees those names alongside the tools they refer to. The cross-references resolve because every name in the prose also appears as a callable tool in the same list. If you rename whatsapp_search to whatsapp_find_contact and don't update the other descriptions, the model still tries to call whatsapp_search and the host returns 'tool not found'.

The model improvises. With a description like 'Send a WhatsApp message to a contact' and no sibling reference, an agent that has just read messages from the active chat will call whatsapp_send_message with whichever contact name appeared most recently in conversation. With WhatsApp specifically, that's how messages get sent to the wrong person, because the model conflates 'the chat I'm looking at' with 'the chat I most recently mentioned by name'. The protocol-style description ('CURRENTLY OPEN', 'Does NOT search', 'verify first') closes that gap by giving the model an explicit anti-pattern to avoid. The cost is verbosity, the benefit is fewer wrong-chat sends.

Because the description is delivered as a JSON string into the model's context. Markdown bold and quotes survive, but ALL CAPS is the most compact and unambiguous emphasis that survives any tokeniser and any host that re-renders the description. In whatsapp-mcp-macos's source, you can see this used sparingly: 'CURRENTLY OPEN' once, 'NOT' twice, 'OPEN' once. Used for every word, capitalisation stops working as a signal. Used for the one or two facts the model must not misread, it's the cheapest possible attention mechanism.

Yes. They are literal Swift string literals at lines 993 to 1108 of Sources/WhatsAppMCP/main.swift in the whatsapp-mcp-macos repo. The file is a single MCP server entrypoint; everything after `func setupAndStartServer()` declares Tool values whose `description:` argument is the string the model sees. There are 11 tools and 11 description strings. The longest is whatsapp_send_message at 31 words. The shortest is whatsapp_quit at 4 words ('Quit/close WhatsApp.'). The variation is intentional: tools with state-changing side effects get protocol prose, tools without them get a verb.