Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
StateSet MCP server has solid naming conventions and reasonable descriptions, but exhibits significant gaps in parameter documentation, output schema clarity, and error handling guidance. Of 13 tools, most follow verb_noun naming patterns well (search_*, stateset_*, create_rma, etc.). However, parameter descriptions are inconsistent, many lack detail about format, constraints, or error recovery paths. Output schemas are not documented in the tool definitions. Error handling is minimal; tools do not provide recovery guidance or explain when/why to retry. The server uses STDIO transport, which is a hard architectural constraint that caps protocol readiness at 50.
Output schemas are not documented in tool definitions. LLMs cannot infer what fields each tool returns, forcing trial-and-error discovery and wasting tokens on parsing unstructured responses.
Parameter descriptions lack actionable constraints. 'channel' in stateset_websocket_monitor has no format guidance. 'fields' in stateset_export_search_results offers no examples or valid values. 'message' is typed as object but internal structure is undocumented.
No error handling guidance. Tools do not explain recovery paths, retry eligibility, or when to call alternative tools. E.g., stateset_get_rma lacks 'If RMA not found, try stateset_list_rmas with filters' guidance.
stateset_get_rma
Recommendations
Add explicit output schema documentation to every tool. Include example response JSON showing all returned fields, their types, and semantics. E.g., stateset_get_rma should show: {rma_id: string, order_id: string, status: 'pending'|'approved'|'rejected', items: [{item_id, quantity, status}], created_at: ISO8601}
Enhance parameter descriptions with format and constraint hints. Replace 'Channel name' with 'Channel name (lowercase, alphanumeric + hyphens, max 50 chars)'. Replace 'Filter conditions' with 'Array of {field, operator, value} where operator is one of: eq, ne, gt, gte, lt, lte, in, nin, contains, starts_with, ends_with'.
Add recovery guidance to error scenarios. For stateset_get_rma: 'If RMA not found, call stateset_list_rmas with customer_email filter to find valid RMA IDs. If still not found, the RMA may have been deleted, check stateset_search_orders_by_date to verify the associated order exists.'
Document pagination behavior explicitly. For stateset_list_rmas: 'Returns up to per_page results (default 20, max 100). Page numbers are 1-indexed. Response includes total_count for determining next page. If page exceeds available data, returns empty array.'
Add idempotency hints to WRITE tools. For stateset_create_rma: 'Idempotent if called with same order_id + items + reason within 24 hours; returns existing RMA instead of creating duplicate. After 24 hours, repeated calls create new RMAs.'
Clarify when tools accept system IDs vs human-readable names. E.g., stateset_search_orders_by_date accepts customer_email (human-readable) but what about order_id? Does it accept order_number or only system ID? Make this explicit.
Score history
Overall score trend
↓ 48 points across a rubric change (v1 → v2)
13/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
F
13
<=2025-11-25
v2
2026-03-09
C
61
-
v1
read only
auth
source verified
Search products with inventory levels and availability
Minimal descriptions for READ_ONLY vs WRITE risk classification. Tools like stateset_cache_management (WRITE) and stateset_create_rma (WRITE) lack explicit state-change warnings that would help agents understand irreversibility.
Pagination not clearly specified. stateset_list_rmas accepts 'page' and 'per_page' but no description explains if page is 0-indexed or 1-indexed, what happens if per_page exceeds limits, or whether a total_count is returned.
Inconsistent parameter naming conventions. stateset_advanced_search uses 'per_page' while stateset_list_rmas uses 'per_page', consistency is good, but 'sort' vs 'sort_by' in different tools creates ambiguity.
Add examples of valid enum values in descriptions. For stateset_websocket_monitor action enum ['status', 'subscribe', 'unsubscribe', 'broadcast']: 'Action to perform on the WebSocket connection. status = report current subscriptions; subscribe = add listener to channel; unsubscribe = remove listener; broadcast = send message to all subscribers on channel.'
Document response size limits. E.g., stateset_full_text_search: 'Returns up to limit results per resource (default 10, max 50). Results are ranked by relevance. Large queries may be truncated; use stateset_advanced_search for exhaustive results.'
Separate tools with overlapping concerns. stateset_saved_search handles create, list, get, update, delete, AND execute, this violates single-responsibility. Split into stateset_create_saved_search, stateset_list_saved_searches, stateset_execute_saved_search for clarity.
Add timestamp format guidance. Parameters like date_range.start use 'ISO 8601' but should clarify: 'ISO 8601 date-time (e.g., 2024-01-15T14:30:00Z or 2024-01-15T14:30:00-05:00). Timezone-naive timestamps assume UTC. Microsecond precision supported.'.