Static source inference · medium confidence · evidence: Streamable HTTP
Current-spec patterns detected
Summary
MCP server LangGraph exhibits poor definition quality with critical gaps across naming, descriptions, and schema completeness. Tool definitions appear to originate from a deprecated/archived code generation script (scripts/archive/unused/generate_mcp_tools_openapi.py), not from live server implementation. The tools are READ_ONLY conversational/retrieval operations, but lack proper parameter descriptions for critical fields (user_id, token), missing output schema documentation, and descriptions that are too generic to guide LLM tool selection. The presence of sensitive JWT token parameters exposes a security anti-pattern. No evidence of actual tool registration logic in the active codebase; definitions appear inferred rather than directly implemented.
Credentials exposed as tool parameters: JWT token parameter in all three tools violates secret-injection pattern. Tokens should never appear in agent-callable parameters, they will be logged in traces, prompt history, and agent logs.
Missing output schema documentation: None of the three tools document what fields their responses contain. LLMs cannot plan downstream calls or extract required data without knowing the response structure (e.g., what IDs to use in follow-up calls).
Generic/insufficient parameter descriptions: user_id and token parameters lack descriptions explaining their purpose, format, or origin. 'User identifier for authentication and authorization' is vague, does it accept email, UUID, or username? How should the LLM obtain it?
agent_chatconversation_getconversation_search
Recommendations
Remove 'token' as a tool parameter immediately. Implement server-side secret injection via environment variables or a secure vault. Authenticate the calling agent via MCP protocol headers, not via exposed JWT parameters in tool inputs.
Expand tool descriptions to 50-200 chars, following LLM-optimized patterns. Example: 'agent_chat' → 'Send a message to the AI agent and receive a streaming response. Supports multi-turn conversations via thread_id. Returns structured agent output with action metadata.'
Document the output schema for each tool. Specify response fields (e.g., agent_chat returns {id, message, action, thread_id, metadata}). Include chaining IDs so downstream tools can operate without additional lookups.
Add comprehensive parameter descriptions. For user_id: 'Unique identifier for the user (UUID format from MCP session context)'. For token: remove and replace with server-side authentication. For thread_id: 'Optional conversation thread ID (UUID). Omit to start a new conversation.'
Verify tool registration in live server code. The definitions appear in an archived script; confirm they are actually registered in the active MCP server implementation (likely in src/mcp_server_langgraph or equivalent). If not, move definitions to the canonical source.
Add error handling guidance to descriptions. E.g., agent_chat: 'Returns streaming response. On auth failure, verify user_id is valid. On thread not found, start a new conversation by omitting thread_id. On timeout, retry with a shorter response_format.'
Tool definitions sourced from archived code generation script: Tools defined in scripts/archive/unused/generate_mcp_tools_openapi.py, not from active server implementation. This suggests the definitions are stale, inferred, or not actually registered in the live MCP server. Cannot verify if tools are actually implemented.
Minimal tool descriptions: agent_chat ('Chat with AI agent (supports streaming)') and conversation_get ('Retrieve a conversation by thread_id') are too brief (11-36 chars) to guide LLM selection. Per baselines, descriptions should be 34-392 chars (p10-p90); these fall at the lower extreme.
Ambiguous parameter naming without type suffixes: Parameters named 'user_id' and 'token' lack clarity on expected format (UUID vs slug vs email). No suffix distinction (e.g., user_id_uuid vs user_id_email) forces LLM guessing.
Missing error handling guidance: No documented error scenarios, recovery paths, or actionable error messages. If agent_chat fails to find a thread_id or auth fails, what should the LLM do next?
No pagination support documented: conversation_search has a limit parameter (good), but no documentation of whether results are paginated, what happens at limit, or how to fetch the next page. Large result sets will blow context windows.
conversation_search
Document pagination in conversation_search. Clarify: 'Results are limited to the specified limit (default 10, max 50). If total exceeds limit, include a next_offset or next_cursor in the response to fetch additional conversations.'
Validate parameters early with actionable errors. E.g., if response_format is invalid: 'Invalid response_format: got "verbose", must be one of: concise, detailed. Concise is recommended for faster responses.'
Consider splitting agent_chat: one tool for initiating conversations (chat_start), one for streaming responses (chat_stream). Clarifies intent and enables independent tool selection.