Server defines 3 tools with complete input schemas and basic descriptions. However, descriptions are generic and lack LLM-optimized guidance on WHEN to use each tool vs. alternatives. Parameter descriptions are present but minimal. No output schemas are documented. Error handling is present but not recovery-focused. Tool names follow verb_noun convention (good), but descriptions do not differentiate tools adequately or provide context about prerequisites, side effects, or dependencies. Average description length ~70 chars (baseline 194 chars), significantly below production standard.
Tool descriptions lack LLM-optimized context. Descriptions do not explain WHEN to use each tool, what happens to state, or how tools compose. 'Send a message to a Facebook Messenger user' does not answer: Is this synchronous? Does it queue? Can it fail? When should I use this vs. send_typing_indicator? This forces LLMs to guess and risks wrong tool selection.
No output schemas documented. Tool responses return generic text objects without defined field structure. LLMs cannot plan downstream calls or extract typed data. E.g., send_message returns a plain text response with 'Message ID' embedded in prose, should be structured JSON with { message_id, timestamp, status }.
Parameter descriptions are minimal and lack format/constraint guidance. E.g., 'recipient_id' described as 'The PSID (Page-Scoped ID) of the recipient', does not explain format, length, or pattern. 'action' enum is documented but lacks explanation of when to use typing_on vs. typing_off vs. mark_seen.
Recommendations
Expand send_message description to: 'Send a text message to a Facebook Messenger user by their Page-Scoped ID (PSID). Messages are delivered asynchronously and cannot be edited or deleted. Use this for direct communication; use send_typing_indicator to show activity without sending content. Returns message_id on success. May fail if PSID is invalid or user has opted out.'
Expand get_user_info description to: 'Retrieve public profile information for a Messenger user (first_name, last_name, profile_pic). Read-only; does not modify user data. Returns empty result if user has not shared info with the page. Call this before send_message if you need to verify user exists or get their name for personalization.'
Expand send_typing_indicator description to: 'Send a typing indicator or mark-as-seen signal to a user. typing_on shows a typing bubble; typing_off hides it; mark_seen marks messages as read. These actions do not send messages, use send_message to deliver content. Typing indicators typically timeout after ~20 seconds.'
Document output schemas for each tool. E.g., send_message should return { message_id: string, recipient_id: string, timestamp: ISO8601, status: 'sent' | 'failed' }. get_user_info should return { user_id: string, first_name?: string, last_name?: string, profile_pic_url?: string }.
Add parameter descriptions: recipient_id should state 'Page-Scoped ID (PSID), a numeric string assigned by Facebook for this page. Typically 15-20 digits.' action enum values should each be described: 'typing_on: show typing bubble (lasts ~20s), typing_off: hide typing bubble, mark_seen: mark all messages as read.'
Error handling returns plain text errors without recovery guidance. Catch block returns 'Error: {message}', does not tell LLM if error is retryable, user-fixable, or fatal. E.g., 'Invalid PSID' should suggest 'Try get_user_info first to verify the user exists.'
Tool descriptions lack mutation semantics. send_message and send_typing_indicator modify external state (send to Facebook), but descriptions do not explicitly state 'This action is irreversible' or 'Messages cannot be recalled.' Agents need this metadata to reason about safe retries.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). get_user_info should have readOnlyHint: true. send_message and send_typing_indicator should have destructiveHint: true or idempotentHint flags to guide agent behavior.
Credentials (FB_PAGE_ACCESS_TOKEN) exposed as environment variable injection, not tool parameters, correct. However, no mention in tool descriptions that agents must be configured with valid Facebook credentials, or what happens if token is missing/expired. This creates silent failures.
Add tool annotations to mcp-server.ts tool definitions: get_user_info with readOnlyHint: true, send_message and send_typing_indicator with destructiveHint: true. This helps agents avoid retrying non-idempotent operations unnecessarily.
Add validation inside tools before calling Facebook API. E.g., validate recipient_id matches PSID pattern (numeric, 12-20 chars). Return clear validation errors: 'Invalid recipient_id format: must be numeric. Got: "user-123".'
Document prerequisites in send_message description: 'Requires FB_PAGE_ACCESS_TOKEN environment variable set with a valid Facebook Page access token. Token must have messages:manage scope.' This clarifies setup requirements.