MCP server for Twilio SMS with AI-powered conversation management
The server has 5 tools with complete input schemas visible in src/server.ts. All tools are properly named with action verbs (send_, get_, create_) and descriptions are present. However, several issues limit the score: (1) Descriptions are mostly generic and lack WHEN/WHY guidance; (2) Parameters lack type information in descriptions (e.g., 'phone number in E.164 format' is stated in description but not validated); (3) Output schemas are NOT documented, tool responses are JSON stringified but no structured schema is declared for the LLM; (4) Error handling is minimal, no recovery guidance visible in error paths; (5) No enum constraints on parameters that should be restricted (e.g., message limits, status values). Tool names follow verb_noun convention well. Parameters are reasonable but lack consistency in documentation depth.
Initialize a new conversation thread between participants.
Retrieve full conversation history with all messages.
Query received SMS/MMS messages from storage with optional filters.
Check the delivery status of a sent message.
Send an SMS message via Twilio. Automatically creates or links to a conversation thread.
NO OUTPUT SCHEMAS DOCUMENTED. All 5 tools return JSON-stringified results, but the structure is not declared in tool definitions. LLMs cannot plan downstream calls or extract required fields without guessing at response structure.
DESCRIPTIONS LACK ACTION-ORIENTED CONTEXT. All descriptions focus on WHAT (e.g., 'Send an SMS message') but omit WHEN and WHY. No guidance on dependencies or recovery paths. E.g., 'send_sms' doesn't explain when to use vs. get_conversation_thread, or that it requires a valid phone number.
MISSING SCHEMA CONSTRAINTS. Parameters like 'limit' (50-1000) and 'participants' (minItems: 2) are described in English but not encoded in JSON Schema. LLMs ignore English constraints and pass invalid values.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 53 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 42 | - | v1 |
NO ERROR HANDLING GUIDANCE. Errors are not caught/handled visibly in the tool handler (CallToolRequestSchema block). If a tool fails, no recovery suggestions. E.g., if messageSid is invalid, no hint to search for the correct SID.
NO PAGINATION GUIDANCE FOR LIST TOOLS. 'get_inbound_messages' defaults to limit=50 but provides no cursor/next_page mechanism. If results exceed limit, how does the agent fetch the next batch?
OVERLOADED/UNDERSPECIFIED PARAMETERS. 'metadata' in create_conversation is type 'object' with no properties, too permissive. 'conversationId' in get_conversation_thread lacks guidance on what happens if it doesn't exist.
MISSING OUTPUT FIELD ALIGNMENT. If 'send_sms' returns message_sid, and 'get_message_status' accepts messageSid parameter, they must match exactly. Cannot verify from source whether response field names match parameter names.