This STDIO-only MCP server for Nad.fun (a Monad blockchain token trading platform) suffers from severe quality issues across naming, descriptions, and schema documentation. While 21 tools are registered in src/index.ts, most lack comprehensive input/output schema visibility in the provided code. Only 1 tool (token-chart, #10 and sell-tokens-to-curve, #21) show explicit input schema in the audit. Tool descriptions are present but generic (average ~60 chars, well below the 194-char baseline). Destructive operations (transfer-mon, buy/sell tokens) lack dry-run or confirmation patterns, and private key handling in tool parameters violates secret-injection rules. The codebase structure (imports from ./tools/ and ./app/) suggests schema definitions exist elsewhere, but they are not provided for verification.
19 of 21 tools have input schemas registered but not visible in source code provided. Cannot verify schema completeness, parameter types, or descriptions per scoring rubric. Only token-chart and sell-tokens-to-curve schemas are visible.
Private key exposed as tool parameter in sell-tokens-to-curve (and likely buy/sell operations). Credentials must never be tool parameters; they enter agent logs and context. Use server-side secret injection via environment variables or vault.
Recommendations
URGENT: Refactor all destructive operations to support dry-run or confirmation. Add parameters like `dryRun: boolean` or `confirmationToken: string` (returned from a separate confirm_transfer tool). Example: buy-tokens-from-curve returns {confirmationToken, estimatedCost, slippage}, then execute-buy-tokens accepts confirmationToken to commit.
URGENT: Move private key from tool parameters to server-side secret injection. Store private keys in .env or a secure vault (AWS Secrets Manager, HashiCorp Vault). Tools should accept only wallet address or account name, not secrets.
CRITICAL: Export and document all input/output schemas from ./tools/ files (tokenSearch.ts, tokenStats.ts, etc.). Each schema must include: parameter name, type, description, constraints (min/max, enum, regex), and return fields. Verify completeness against the visible schema definitions.
HIGH: Enhance descriptions with WHEN context. E.g., 'List tokens ordered by market cap (highest first) to identify leading projects and compare competitor valuations.' Current descriptions tell WHAT but not WHY.
HIGH: Add toolAnnotations to all tools. Use destructiveHint for transfer-mon and all buy/sell tools. Use readOnlyHint for search and list tools. Example in MCP: {destructiveHint: true, confirmationRequired: true}.
HIGH: Document output schemas explicitly. For list operations, specify: returns {tokens: [{address, symbol, name, marketCap, holders, lastTradedAt, ...}], total: number, nextCursor?: string}. For single-item tools, specify all returned fields.
Destructive operations (transfer-mon, buy-tokens-from-curve, buy-tokens-from-dex, sell-tokens-to-curve, sell-tokens-to-dex) lack dry-run or confirmation step. Agents make mistakes, LLM could accidentally execute irreversible blockchain transactions without user approval.
Tool descriptions are generic and under 100 chars for most tools (e.g., 'Get tokens ordered by creation time' is 41 chars). Descriptions should be 50 - 200 chars and include WHEN to use the tool. E.g., 'List tokens by newest first to discover emerging projects before market cap grows.'
No output schema documentation visible. Responses must document what fields are returned, especially for list operations. E.g., list-tokens-by-market-cap should document: returns array of {address, symbol, name, marketCap, 24hChange, ...}, total count, and pagination cursor if needed.
No toolAnnotations (readOnlyHint, destructiveHint, idempotentHint) declared. Destructive operations should be marked with destructiveHint to help clients/LLMs understand irreversibility. READ_ONLY and DESTRUCTIVE marks in audit are not in MCP schema.
Tool names use hyphens (e.g., search-tokens, get-mon-balance). While valid, LLMs prefer verb_noun or verbNoun (search_tokens, getMONBalance). Current names work but are less discoverable.
MEDIUM: Implement paginated results for list tools. Accept limit (1-100, default 20) and cursor/offset parameters. Return total count and nextCursor to enable agent-driven pagination without context explosion.
MEDIUM: Add error handling guidance in tool descriptions. E.g., 'If token not found, returns {error: 'Token not found', suggestion: "Try search-tokens()"}'. Implement recoverable vs fatal error classification.
MEDIUM: Add parameter descriptions for all visible schemas. token-chart shows baseTimestamp as optional but no description. Verify all 21 tools have per-parameter descriptions explaining constraints, format, and purpose.
LOW: Consider renaming tools from kebab-case (search-tokens) to snake_case (search_tokens) for better LLM parsing. Tool names like search_tokens_by_symbol might be clearer than search-tokens.