Static source inference · medium confidence · evidence: Streamable HTTP
Current-spec patterns detected
Summary
This server exhibits critical definition quality gaps across nearly all dimensions. While 21 tools are registered with names and basic descriptions, the implementation lacks formal MCP tool registration patterns, proper schema documentation, and standard parameter descriptions. Tool names follow verb conventions but lack precision. Descriptions are present but generic (averaging ~15-20 chars for tools like 'Get reports list', below the 34-char p10 baseline). Input schemas are inferred from route parameters rather than explicitly defined in an MCP-compliant tool manifest. Parameter descriptions exist in the schema but are minimal. Output schemas are completely undocumented. Error handling is present at the HTTP layer but lacks LLM-friendly recovery guidance. The server implements Express routes that proxy to Wildberries APIs but does not register tools in the standard MCP Server protocol format visible in the source code.
Descriptions are critically short and lack context. Tools like 'Get reports list' (12 chars) and 'Get campaign statistics' (24 chars) fall far below the 34-char p10 baseline and provide no indication of WHEN to use the tool, WHAT it returns, or dependent steps. This violates pattern:tool-description and forces LLMs to guess tool selection criteria.
CRITICAL: Expand tool descriptions from 12-24 characters to 100-200 characters. Each must answer: (1) What does this tool do? (2) When should I use it instead of a similar tool? (3) What does it return? Example: 'Get campaign statistics (impressions, clicks, spends) for a specific ad campaign during a date range. Use this to analyze overall campaign performance; use get_campaign_statistics_by_key_phrases for phrase-level breakdown. Returns campaign metrics including daily breakdown.'
CRITICAL: Document output schemas for every tool. Create a schema file or inline documentation showing example response structures. Include field names, types, and meanings. For example, for get_campaign_statistics: {"campaignId": integer, "metrics": {"impressions": integer, "clicks": integer, "spends": float}, "dates": ["2024-01-01", ...]}. This enables LLM tool chaining.
CRITICAL: Migrate from Express route-based implicit tool registration to explicit MCP ToolDefinition registration. Tools should be defined in a tools array with name, description, inputSchema, and outputSchema properties conforming to the MCP spec, not inferred from routes.
HIGH: Expand parameter descriptions to include format, constraints, and units. For dateFrom/dateTo: 'Start/end date in ISO 8601 format (YYYY-MM-DD). Must be within the last 2 years. Dates are inclusive.' For campaignId: 'Your Wildberries campaign ID (integer, find in your account dashboard).' For nmID array: 'Product IDs (1-100 items per request; see documentation for batch APIs for larger sets).'
Input schemas exist in the route handlers but are inferred from parameter documentation, not formally registered in an explicit tool definition manifest or MCP ToolDefinition structure. Tools are implicitly defined via Express routes, not explicitly declared with a proper tools list. This is not standard MCP server registration.
Output schemas are completely undocumented. The source shows API response handling in callWbApi() but provides no description of what fields are returned, their types, or how downstream tools should interpret them. This violates pattern:tool (which requires documenting return types) and breaks tool chaining, the LLM cannot plan multi-step queries without knowing what data is available.
Parameter descriptions are minimal (averaging 5-15 chars: 'Campaign ID', 'Start date for statistics'). These fall far below the 72-char baseline and provide no format hints, constraints, or units. Tools like dateFrom/dateTo lack specification of ISO 8601 vs other formats, timezone handling, or range limits. This forces LLMs to infer format from context, causing date parsing errors.
Error handling is present at the HTTP layer (401/429/4xx handling in callWbApi) but responses lack LLM-friendly recovery guidance per pattern:recovery-guide. Errors return a message and status but do NOT tell the agent what to try next. E.g., a 401 auth error should suggest 'Check your API key' or retry; a 429 should suggest waiting or batching requests differently. Without guidance, agents cannot self-correct.
No pagination support documented or enforced. Tools returning lists (get_stocks_report_products, get_search_report_table_groups, get_reports_list) do not expose page/limit parameters or document result limits. Without pagination, large result sets blow context windows and violate pattern:paginated-result. Tools should accept limit and offset/cursor parameters and return next_cursor or total_count.
No tool chaining support visible. Tools return data from Wildberries APIs but do not guarantee return of IDs/references needed for follow-up calls. For example, if get_campaign_statistics returns campaign data, does it include campaign_id for use in get_automatic_campaign_statistics_by_phrase_clusters? Without visible response schemas, LLMs cannot plan multi-step workflows.
API key is accepted as an HTTP header ('api-key') in the authMiddleware but the schema shows no API_KEY parameter exposed to tools. This is actually correct from a security standpoint per pattern:secret-injection, but the lack of documentation about how credentials are injected is unclear. The server should document that API keys are provided via environment/server config, not tool params.
Two tools (create_csv_report and regenerate_report) modify state (marked WRITE) but have no dry-run or confirmation step. Per pattern:confirmation-request, irreversible operations should support an explicit confirmation. Agents may accidentally generate or regenerate reports repeatedly without intent.
Tool names are generally good (verb_noun format) but lack precision in distinguishing overlapping functionality. Multiple tools retrieve 'product card statistics' (for_period, by_days, grouped) with nearly identical names and parameter sets. LLMs may struggle to choose the right variant without detailed descriptions explaining when each is appropriate. This violates pattern:tool (clarity between similar tools).
HIGH: Add actionable error guidance. Wrap error responses to tell agents what to do next. For 401 auth errors: 'Authentication failed. Verify your API key is correct and has analytics:read scope.' For 429 rate limit: 'Rate limited. Wait 60 seconds before retrying, or batch requests into larger chunks.'
HIGH: Implement pagination for list-returning tools. Add optional limit (1-100, default 20) and offset/cursor parameters. Return total_count and next_cursor in responses. For get_reports_list: 'Returns paginated list of reports. Use limit (default 20) and offset to navigate. Returns {reports: [...], total_count: 42, next_offset: 20}.'
HIGH: Document differences between similar tools. Add a dependency hint in get_product_card_statistics_by_days: 'Returns daily breakdown. Use this for trend analysis over time. If you need totals by product without daily splits, use get_product_card_statistics_for_period instead.' This helps LLMs choose correctly.
MEDIUM: Add a confirm_before_create_report step or dry_run parameter to create_csv_report. This prevents agents from accidentally generating duplicate reports. Example: 'create_csv_report with dry_run=true returns a preview of the report without generating it; confirm with dry_run=false to actually create.'
MEDIUM: Document which parameters are required vs optional. For example, does regenerate_report require additional parameters beyond downloadId? Are dateFrom/dateTo always required or optional? Use JSON Schema required array and note in descriptions: 'Required: campaignId. Optional: dateFrom, dateTo (defaults to last 30 days).'
MEDIUM: Add a discovery tool or document available report_types. create_csv_report accepts reportType but no enum or description of valid values. Either add an enum in the schema or create a get_report_types tool that lists valid options, enabling the LLM to suggest valid choices.
MEDIUM: Return all chaining IDs in responses. If a user searches campaigns, the response must include campaign_id so they can immediately query statistics without an extra lookup. Document what IDs are returned by each tool.
LOW: Consider adding sampling support for cost-constrained analytics queries. Per pattern:sampling, for expensive queries (e.g. full_product_statistics_grouped), offer a sample_pct parameter. This lets agents explore data cheaply before committing to full queries.