Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
The server demonstrates reasonable definition quality with consistent naming patterns, present descriptions, and documented schemas. However, there are notable gaps: descriptions are often generic or underbaked (many under 100 chars), parameter descriptions lack actionable detail (missing format constraints, ranges, dependencies), error handling is basic (no recovery guidance), and no tool annotations are present. The tool-handler shows error categorization but this does not translate to user-facing recovery guidance. Most tools follow verb_noun naming correctly (create_, get_, list_), but parameter naming could be more specific (e.g., 'customer' object lacks field detail). Output schemas are not explicitly documented for any tool, only input schemas are provided. Compared to production baselines (avg description 194 chars, 100% of A+ tools have docstrings and param descriptions), this server is solidly middle-of-pack.
Output schemas not documented. Tools return results but no schema or field list is provided to LLMs. This prevents the LLM from planning downstream calls and extracting the right data.
Parameter descriptions lack actionable detail. No format constraints, ranges, or dependencies documented. E.g., 'amount' has no range (cents? integer?), 'status' in list_charges has no enum of valid values, 'customer' in create_charge is described as 'Customer information' but sub-fields are undefined.
Document output schemas for every tool. Include a 'Returns' section in each tool docstring listing all returned fields, their types, and meanings. Example: 'Returns: {charge_id: string, amount_cents: number, status: "pending"|"completed"|"failed", created_at: ISO8601 string}'.
Expand tool descriptions to 100-150 characters. Follow the pattern: '[VERB] [OBJECT] [OUTCOME]. Use this when [CONTEXT]. Returns [KEY FIELDS].' Example: 'Create a new charge request. Use this to initiate a payment when a customer provides payment details. Returns charge_id, status, and payment_url.'
Add enums and constraints to parameters. For status fields, replace free-form strings with enums: {enum: ["pending", "completed", "failed", "cancelled"]}. For amounts, add {type: "number", minimum: 1, description: "Amount in cents, e.g., 1000 = R$10.00"}.
Expand parameter descriptions with format and validation rules. Replace 'Charge amount in cents' with 'Charge amount in cents (integer, minimum 1, e.g., 1000 = R$10.00)'. Replace 'Filter by start date (ISO 8601)' with 'Filter by start date (ISO 8601, e.g., 2024-01-15T00:00:00Z)'.
Add tool annotations. Register each tool with readOnlyHint=true for get_* and list_*, and destructiveHint=true for create_* and delete_* operations. This lets LLMs reason about retry safety.
Spec posture evidence
Inferred effective spec: 2025-06-18+.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Score history
Overall score trend
↓ 10 points across a rubric change (v1 → v2)
43/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
F
43
2025-06-18+
v2
2026-03-09
D
53
-
v1
get_refundread onlyauth50/100
Retrieve a specific refund by ID
get_transactionread onlyauth50/100
Retrieve a specific transaction by ID
list_accountsread onlyauth50/100
List all accounts
list_chargesread onlyauth50/100
List charges with optional filtering by status, date range, customer, or subscription
list_customersread onlyauth50/100
List customers with optional search, skip, and limit parameters
list_refundsread onlyauth50/100
List refunds with optional filtering
list_transactionsread onlyauth50/100
List transactions with optional filtering by date range, charge, PIX QR code, or withdrawal
Tool descriptions are short and generic (avg ~55 chars). Do not explain WHEN to use this tool vs similar ones, what it returns, or any prerequisites. E.g., 'Create a new charge in the Woovi system' does not explain if it blocks until payment or is async, or what fields are required.
No error recovery guidance. formatToolError() categorizes errors (VALIDATION_ERROR, RATE_LIMIT_ERROR, etc.) but does not suggest next steps. E.g., when a charge is not found, the response should suggest 'Try list_charges() with a date filter.' Instead, LLM receives only 'Error: not found'.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). All tools lack metadata about side effects. LLMs cannot distinguish which tools are safe to retry (get_*, list_*) vs destructive (create_*, create_refund). This prevents smart agent planning.
Ambiguous nested parameter. 'customer' in create_charge is described as an object but fields are undefined. LLM does not know what sub-fields to provide (name? email? ID?). Unpack into separate parameters or document the object schema.
Parameter naming inconsistency. Some tools use 'correlationID' (camelCase), others use conventional snake_case. LLMs expecting snake_case may fail to map 'chargeId' vs 'charge_id'. Standardize on one convention.
No pagination documentation. list_* tools accept skip/limit but no mention of total count, next cursor, or max limit. Large result sets could blow context windows. Cap results at 50 and document in descriptions.
Enhance error responses with recovery guidance. In formatToolError(), check error category and suggest next steps. Example: for NOT_FOUND on get_charge, return 'Charge not found. Try list_charges() to search by date range or customer.'
Standardize parameter naming to snake_case. Rename 'correlationID' → 'correlation_id', 'chargeId' → 'charge_id' for consistency with REST API conventions.
Document pagination behavior. Add to list_* descriptions: 'Supports pagination (skip, limit). Returns up to [LIMIT] results. Use skip to retrieve additional pages.' Cap default limit at 50 and document max limit.
Add idempotency guidance. For write operations (create_charge, create_customer), document whether correlationID provides idempotency. Example: 'Idempotent: calling twice with the same correlationID returns the same charge (no duplicate created).'
Create a dependency matrix. Document which tools chain together. Example: 'create_charge → create_transaction (needs charge_id from response).' Include this in tool descriptions under 'Typical flow:'.
Add rate limit and timeout information. Document expected latency, rate limits (if any), and timeout behavior. Example: 'Returns in <100ms. Rate limit: 100 requests/minute per API key.'