Tool descriptions are uniformly short (30-60 chars) and lack context about when to use each tool, prerequisites, or guidance for distinguishing overlapping tools (e.g., bth_recent_trades vs bth_aggregate_trades, bth_ticker_price vs bth_ticker_24hr). LLMs cannot infer the difference without expanded descriptions.
Parameters lack constraint documentation. For example, bth_klines 'interval' parameter accepts only specific values (1m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w, 1M) but the description does not state this, it should be an enum or list in the schema. Similarly, 'symbol' parameters accept uppercase alphanumeric format (e.g. BTCTHB) but this is not documented. Numeric limits (e.g., limit max 1000) are mentioned in some descriptions but inconsistently.
bth_order_book
Recommendations
Expand tool descriptions from 30-60 chars to 100-200 chars. Add context about WHEN to use each tool (e.g., 'Get current price for real-time quotes (bth_ticker_price) vs 24hr change stats (bth_ticker_24hr) for trend analysis.'). Reference Baseline: 194 chars average for A+ tools.
Add formal enum constraints to parameters with fixed valid values. For bth_klines, add enum=['1m', '5m', '15m', '30m', '1h', '2h', '4h', '6h', '8h', '12h', '1d', '3d', '1w', '1M'] instead of just describing in text. Same for bth_new_order's 'side' (BUY|SELL) and 'type' (LIMIT|MARKET|STOP_LOSS_LIMIT|etc).
Document all parameter constraints in descriptions: symbol format (uppercase, e.g. BTCTHB), numeric limits (limit 1-1000), required field combinations (orderId OR origClientOrderId), and defaults. Pattern: 'Maximum 1000 records; default 500.'
Add tool annotations to high-risk operations. Mark bth_cancel_all_orders and bth_withdraw with destructiveHint=true. Mark bth_new_order with idempotentHint=true if a newClientOrderId prevents duplicates, else mark as WRITE risk.
Document output schemas for all tools. For market data tools, show structure: {symbol, price, timestamp, ...}. For account tools, show {balances: [{asset, free, locked}], ...}. This enables LLMs to plan extraction and chaining.
Add recovery guidance to error messages. For example, if bth_new_order fails due to insufficient balance, return: 'Insufficient balance. Call bth_account_info() to check available balances, or bth_deposit_address() to deposit.'
High-risk operations (bth_cancel_all_orders, bth_withdraw, bth_new_order, bth_sub_account_transfer) lack tool annotations to signal destructive or irreversible behavior. MCP supports destructiveHint and idempotentHint annotations. Without these, LLMs may not recognize the severity of these operations.
Output schemas are not documented. The source code does not show what structure each tool returns (e.g., what fields are in the order book response, trade response, account info). LLMs need documented return types to plan downstream calls and extract relevant fields.
Error handling is generic. The tool registration in server.ts catches all errors and returns a plain error message text. There are no recovery guides, error classification (retryable vs fatal), or actionable next steps. Example: if bth_withdraw fails because the address is invalid, the error should suggest 'Try bth_deposit_address() to verify valid addresses for this coin.'
Overlapping tool purposes are not differentiated. bth_ticker_price (latest price single/all) vs bth_ticker_24hr (24hr stats) and bth_recent_trades (last N trades) vs bth_aggregate_trades (filtered by time/ID range) perform related functions but the descriptions do not explain when to use one vs the other.
Mutually exclusive parameters (e.g., in bth_query_order: orderId vs origClientOrderId, and in bth_new_order: quantity vs quoteOrderQty) are not documented as such. Descriptions should state 'Either orderId or origClientOrderId must be sent' and 'For MARKET orders, use quoteOrderQty instead of quantity.'
bth_query_orderbth_new_order
Clarify overlapping tools with decision trees in descriptions. Example for bth_ticker_price: 'Get latest price for a single symbol or all symbols. Use bth_ticker_24hr() for 24-hour change stats and volume instead.'
Document mutually exclusive parameters explicitly. For bth_query_order: 'Either orderId or origClientOrderId must be sent (not both).' For bth_new_order: 'LIMIT orders require quantity + price + timeInForce. MARKET orders require quantity or quoteOrderQty (not both).'
Add per-parameter type information where missing. Ensure all numeric parameters have minValue/maxValue documented (e.g., limit: 1-1000, recvWindow: 1-60000). Ensure all enum parameters declare valid values.
Implement rate limiting guidance. Add to descriptions of write operations: 'Subject to Binance rate limits. If rate-limited (429 error), wait and retry.'
Consider batching variants for common use cases. If agents often fetch multiple symbols' prices/tickers, offer bth_ticker_price_batch(symbols: string[]) to reduce round-trips.
Document parameter dependencies. For bth_aggregate_trades: 'Use either fromId (to continue from last aggregate trade ID) or startTime/endTime (to search by time range), but not both.' Similarly for bth_new_order, document how type field determines which other params apply.