Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
MCP-Bridge is a middleware/aggregator that wraps existing MCP clients. Definition quality is significantly compromised by: (1) tool naming inconsistencies and ambiguity, multiple tools named 'call_tool' with different signatures, generic names like 'get_tools' vs 'list_tools' creating confusion; (2) descriptions are present but minimal (10-30 chars), failing to explain WHEN to use each tool or their distinct purposes; (3) input schemas are present but sparse, most parameters lack proper type constraints, no enums for known values, no min/max bounds; (4) output schemas are documented in code but descriptions do not explain what agents should expect, forcing them to guess field names and availability; (5) error handling is absent, HTTP exceptions shown but no recovery guidance or classification. The server exposes 17 tools but 8 are infrastructure/endpoint tools (openai_completions, openai_chat_completions, models, health) that blur the line between MCP tools and HTTP API shims. The bridge design itself is sound, but tool definitions lack the clarity LLMs need for correct selection and composition.
Duplicate tool names break unique identification. 'call_tool' appears twice with different signatures (tool_name vs name parameter). LLMs cannot distinguish between them.
Ambiguous tool name pairs lack distinguishing context. 'get_tools' vs 'list_tools', 'get_server_prompts' vs 'list_prompts', LLMs spend reasoning cycles deciding which to call. Names should disambiguate scope (all vs single server).
Descriptions are uniformly minimal (5-12 words, under 40 chars). Current descriptions lack WHEN/WHY context and do not explain when to call one tool over a near-duplicate. Baseline: descriptions under 20 chars score 0-20.
get_toolslist_toolslist_promptslist_resources
Recommendations
Rename tools to disambiguate scope: 'list_all_tools' (across all servers) vs 'list_server_tools' (single server). Apply same pattern to prompts and resources. Use 'get_server_by_name(name)' for lookup before calling read operations.
Expand ALL descriptions to 50-150 characters. For each tool, document: (1) What it does, (2) When to call it vs similar tools, (3) What it returns (key fields). Example: 'List all tools available from all connected MCP servers. Call this to discover capabilities before calling call_tool. Returns a dict mapping server names to ListToolsResult objects containing tool names, descriptions, and input schemas.'
Add input validation schemas with enums and constraints. For 'server_name' parameters, provide an enum of valid server names or a lookup tool to discover them. For 'arguments' and 'request' parameters, specify the expected structure as a JSON Schema object (not bare 'object').
Document all output schemas in tool definitions. Add a 'Returns' section to each tool description explaining field names, types, and when fields may be absent. Example: 'Returns CallToolResult with fields: content (list of ContentBlock objects), isError (boolean), _meta (dict with execution metadata).'
Implement structured error responses that guide LLM recovery. Instead of raw HTTPException, return: {error: 'tool_not_found', detail: 'Tool xyz not found', suggestions: ['Call get_tools() to list available tools', 'Check server status with get_server_status(server_name)']}
Add a dry_run parameter to call_tool tools (both variants) to enable confirmation workflows. Dry run returns predicted changes without execution. Requires user confirmation before applying.
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Input schemas are absent or invisible for 9 of 17 tools (list_prompts, list_resources, list_resource_templates, list_tools, openai_completions, openai_chat_completions, models, health). These tools provide no parameter guidance to LLMs.
Parameters lack validation constraints. 'server_name' parameters accept any string, no enum of valid server names. 'arguments' and 'request' parameters are bare objects with no structure specification.
Output schemas are not documented in tool definitions. Agents have no way to know what fields to expect from responses, they must infer structure from return type names (ListToolsResult, CallToolResult, etc.) without field documentation.
Error handling provides no recovery guidance. HTTPException(status_code=404) is raised but LLMs receive no context: tool not found, server not found, or parameter validation failed? Rubric requires error responses to say 'what to do next' with a recovery suggestion.
OpenAI endpoint tools (openai_completions, openai_chat_completions, models, health) blur the purpose of an MCP server. These are HTTP API shims, not MCP tools reflecting bridged client capabilities. They belong in HTTP middleware, not the MCP tool catalog.
No pagination or result limits documented. Tools returning lists (list_tools, list_resources, list_prompts, get_tools) have no page/offset/limit parameters.
Remove HTTP endpoint tools (openai_completions, openai_chat_completions, models, health) from MCP tool catalog. Move them to separate FastAPI routers clearly marked as HTTP infrastructure, not MCP tools.
Add pagination support to list tools: accept optional 'limit' (1-100, default 20) and 'offset' (default 0) parameters. Return metadata: {items: [...], total: N, offset: 0, limit: 20, hasMore: bool}.
Add idempotency hints to tool definitions. Use Pydantic Field descriptions or custom annotations to indicate: (1) which tools are idempotent (safe to retry), (2) which tools have side effects, (3) which tools require fresh input each call.
Create a discovery tool 'describe_tool(name)' that returns full tool metadata including parameter schemas, output format, and error responses. This enables agents to self-educate on tool capabilities at runtime.