Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
Single tool 'magento_rest_api' has a comprehensive input schema with 5 parameters, all properly typed. Description is detailed (460+ chars) and explains key concepts (store scope, HTTP methods, pagination). Parameters have good inline documentation. However, output schema is NOT documented, there is no specification of what the tool returns (response structure, fields, data types). This is a critical gap. The tool performs write operations (POST/PUT/PATCH/DELETE) but lacks explicit error handling guidance or recovery instructions for common Magento API failures. Schema validation is present in the code (bool-coerce.js, api-error.js) but not exposed in the tool definition. Tool naming is generic (magento_rest_api) rather than following verb_noun pattern (e.g., 'call_magento_rest_api' or better yet, domain-specific names like 'get_products', 'create_order'). The single all-purpose tool design violates the single-responsibility principle, agents cannot express intent through tool selection alone.
Tools (1)
magento_rest_apiwriteauthsource verified65/100
Run a Magento 2 REST API request against the configured store. Discover exact endpoints and field names via the magento://rest/schema resource (add ?search= to filter). Store scope: use the storeCode parameter (or put it directly in the path after /rest) to target a store for reads AND writes; storeCode "all" = global scope (All Store Views, store_id 0). Reads (GET/HEAD) are safe on any endpoint; writes (POST/PUT/PATCH/DELETE) require a JSON body.
Output schema not documented. Tool returns HTTP responses from Magento API but defines no explicit response structure, field types, or shape. LLMs cannot plan downstream operations or extract required IDs for follow-up calls.
Tool name lacks verb-noun pattern. 'magento_rest_api' is generic; does not convey intent. Splitting into domain-specific tools (list_products, get_product, create_order, update_order) would let LLMs select tools by intent rather than guessing.
No error classification or recovery guidance. Tool can return HTTP errors (4xx, 5xx) from Magento but does not categorize them (retryable vs user-fixable vs fatal) or provide actionable next steps. Code classifies errors (classifyHttpResponse) but error guidance is not exposed to LLM.
Add explicit output schema documentation. Define the structure returned by successful API calls (e.g., 'Success returns HTTP status + JSON body matching the Magento REST API response schema. Common fields: items (array of resources), total_count (number), search_criteria (object). Errors return structured error object with error_code, message, details.'). Without this, agents cannot safely chain calls or extract required IDs.
Split magento_rest_api into domain-specific tools: list_products, get_product, create_product, update_product, delete_product, list_orders, get_order, create_order, list_customers, get_customer, update_customer, search_magento_catalog, etc. Each tool should accept human-readable parameters (sku, email, order_number) and handle store scope internally. This enables agents to express intent through tool selection.
Add error classification to tool description: 'Common errors: 401 Unauthorized (credentials invalid, check token), 400 Bad Request (schema validation failed, see details), 404 Not Found (resource does not exist), 429 Too Many Requests (rate limited, retry after delay). See response.error_code and response.message for specifics.'
Reduce 'query' parameter description length. Extract searchCriteria details into a separate 'Magento Search Guide' resource and reference it from the parameter description. Current description is ~1000 chars; target <200 chars with link to full reference.
Add explicit pagination parameters to tool schema: page_size (1 - 100, default 20), current_page (default 1), sort_field (e.g., 'entity_id', 'name', 'price'), sort_direction ('ASC'|'DESC'). Auto-translate these into searchCriteria query params internally. Agents should use standard pagination syntax, not hand-construct query strings.
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Score history
Overall score trend
↑ 34 points across a rubric change (v1 → v2)
54/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
D
54
<=2025-11-25
v2
2026-03-09
F
20
-
v1
Single all-purpose tool violates single-responsibility principle. One tool handles GET, POST, PUT, PATCH, DELETE across all Magento endpoints. Agents cannot express domain-specific intent (create_product, list_orders, update_customer), everything is a generic 'call API' invocation.
Parameter 'body' accepts multiple types (string, object, array) with anyOf but provides no guidance on when to use each form. Inline examples show JSON string escaping rules but lack clear decision criteria for LLM selection.
No pagination support declared. Tool accepts 'query' parameter for searchCriteria but does not declare limit, offset, or page_size parameters explicitly. LLMs must manually construct query strings rather than using idiomatic pagination params.
magento_rest_api
Document response field naming contract. If an agent needs to update a product retrieved via list_products, what ID field does update_product expect? (sku? product_id? entity_id?) Current responses are Magento API responses, document which fields LLMs must extract for follow-up calls.
Add resource discovery tool or resource. Expose 'magento://rest/schema' as a dedicated resource so agents can browse available endpoints, parameter types, and response fields. Include ?search= query param for filtering by endpoint name (e.g., magento://rest/schema?search=products, magento://rest/schema?search=orders).
Document storeCode behavior more clearly in tool description: 'storeCode determines global vs store-view scope for both reads and writes. Use storeCode="all" for global scope (store_id 0); omit storeCode or use store-specific code for store-view scope. This parameter is required for multi-store setups and cannot be overridden via ?storeId= query param.'
Add dry-run or confirmation support for destructive operations (DELETE, destructive PATCH). Include parameter like 'dry_run' (boolean, default false) for DELETE endpoints. Return 'what would be deleted' before actual deletion. This prevents agent mistakes.
Validate and document body parameter escaping rules with concrete examples. Current description references JSON string escaping with multiple levels of backslash escaping. Simplify with a clear rule: 'For nested JSON strings (e.g., content_constructor_content), use standard JSON escaping only, do not add extra backslashes. Server handles transport escaping automatically.' Provide 1-2 concrete before/after examples.