This MCP server exhibits severe definition quality gaps. While three tools are explicitly defined with basic docstrings, the implementation lacks essential structure for production use: (1) No input parameter schemas are visible, tools accept list/dict arguments but declare no JSON Schema with type definitions, constraints, or validation rules; (2) Tool descriptions are present but generic and lack LLM-optimization guidance (e.g., 'Synthesizes total cost and total revenue...' does not explain WHEN to call this vs alternatives, WHAT prerequisites exist, or the expected data shape); (3) Output schemas are entirely undocumented, callers must infer return structure from code inspection; (4) No error handling or recovery guidance, exceptions raise MarketingAnalystError with no actionable hints; (5) No parameter validation, defaults, or mutual exclusivity documentation; (6) No tool annotations (readOnlyHint, idempotentHint) despite all being read-only analysis tools; (7) Parameters like 'google_ads' and 'analytics' accept loose lists with no shape validation, LLMs cannot reliably construct valid inputs. The server is a thin Python client wrapper with no MCP protocol integration visible in the provided source.
No input schemas visible. Tools accept list and dict parameters with no JSON Schema definitions, type constraints, or property documentation. Tools cannot be called reliably by LLMs without reverse-engineering expected structure from example_usage.py.
Tool descriptions are generic and lack LLM-optimization. 'Synthesizes total cost and total revenue across platforms to calculate Blended ROAS' does not explain when to use this vs similar analysis tools, required data shape, or expected output fields. Descriptions should be 50-200 chars with explicit WHAT/WHEN/HOW guidance.
Rewrite tool descriptions to follow LLM-optimization patterns. Example: 'compute_blended_performance: Calculates Return-on-Ad-Spend (ROAS) across all Google Ads campaigns and store revenue. Call this to measure overall campaign efficiency or benchmark against performance targets. Requires list of campaign objects (with cost, optional conversions) and analytics objects (with revenue). Returns total_ad_spend, total_revenue, blended_roas as float. Assumes $50 average order value per conversion if not provided.'
Document output schemas for all tools. Add a 'Returns' section to each docstring specifying field names, types, and meaning. Example for compute_blended_performance: 'Returns {"total_ad_spend": float, "total_revenue": float, "blended_roas": float}'
Add parameter-level descriptions with constraints. Example: 'google_ads (list, required): Array of campaign objects. Each object MUST have fields {"campaign_id": string (unique), "name": string (human-readable label), "cost": number (USD, ≥0), "conversions": integer (≥0, optional, defaults 0)}. Min 1 item, max 100 items.'
Parameter descriptions missing or extremely brief. 'List of Google Ads campaign objects with cost and optional conversions fields' is the entire param doc, does not specify object shape, required vs optional fields, or valid value ranges.
No error handling or recovery guidance. MarketingAnalystError exceptions are raised but do not tell LLMs what to do next. Example: if google_ads is malformed or empty, agent sees no actionable message, per pattern:recovery-guide, errors must guide next steps.
No tool annotations. All three tools are read-only analysis operations but lack readOnlyHint annotations. Per current spec (2026-07-28), tool annotations are a standard pattern for guiding agent planning and safety.
No MCP protocol transport detected. Source shows only a Python client class and example_usage.py, no evidence of STDIO, HTTP, or SSE transport implementation. This appears to be a standalone Python library, not an MCP server.
Implement parameter validation with actionable error messages. Example: 'Invalid google_ads: expected list of objects with required field "cost". Got: [missing cost field in item 1]. Example valid item: {"campaign_id": "c1", "name": "Search Ads", "cost": 150.50, "conversions": 5}'
Add tool annotations to all three tools. Mark as read-only: {"readOnlyHint": true}. This guides agents that these are safe to call without user confirmation.
Implement MCP server transport. The current Python client is not an MCP server. Wrap it in an MCP STDIO or HTTP server using a framework like mcp-python. Minimum viable wrapper: implement list_tools(), call_tool() handlers that invoke MarketingAnalystClient methods.
Add error recovery guidance. When google_ads is empty, return: 'No campaigns provided. Call fetch_campaigns() to retrieve list, or pass sample: [{"campaign_id": "c1", "name": "Search", "cost": 100.0}]'
Define default behaviors explicitly. Example: 'conversions field defaults to 0 if omitted. ROAS calculation uses revenue / cost; if cost is 0, ROAS returns 0 (not division by zero error).'
Add composition guidance. Document that generate_recommendations depends on output of compute_blended_performance and audit_merchant_center. Describe multi-step workflows so agents can plan sequences.