This Next.js HTTP server exposes 13 tools via API routes, but exhibits significant definition quality gaps across the board. Tool naming is inconsistent (mix of verb_noun, noun_verb, and pure nouns). Most tool descriptions lack clarity on WHEN to use them vs. similar tools, and many are under the 50-char minimum for LLM discoverability. Input schemas are present but sparse, many parameters lack descriptions, and enums are missing where they should exist (e.g., 'plan' accepts 'free|basic|pro|admin' but no enum constraint). Output schemas are entirely absent from the source; the code generates responses but does not document what fields to expect. Error handling is minimal, most routes return generic HTTP status codes without actionable recovery guidance. Two WRITE tools (webhook handlers) lack permission gates and audit logging. The overall effect is that an LLM would struggle to reason about tool selection and would need to guess at parameter semantics.

• Add formal output schemas to every tool. Document response structure as JSON Schema with field names, types, and descriptions. E.g., classroom_chat returns {agentResponses: [{role: string, name: string, emoji: string, content: string}]}
• Add error handling guidance to every tool description and implementation. For each failure mode (skill not found, invalid parameters, external service timeout), specify the error message format and recovery step. E.g., 'If skill not found, return {error: "Skill not found. Available skills: [list]. Try another skill or call list_skills()."}', this guides LLM recovery.
• Add permission gates to WRITE tools (afdian_webhook, lemonsqueezy_webhook, auth_callback). Check caller identity and scope before modifying state. Implement audit logging to record who triggered what action and what changed.
• Remove webhook endpoints (afdian_webhook, lemonsqueezy_webhook, auth_callback) from the agent-callable tool list. These are for receiving external POST requests, not for agents to invoke. Implement them as internal Next.js route handlers that validate origin and signature but do not expose them via the MCP tool protocol.
• Complete parameter descriptions for complex types. For 'history' in classroom_chat, document the required fields and structure: 'Array of {role: string (teacher|assistant|student|user), name: string, emoji: string, content: string}'. For 'milestones' in pbl_chat, document each milestone object: {title: string, description: string, status: string}.
• Add enum constraints to bounded parameters. Convert 'plan' description to schema enum: {type: 'string', enum: ['free', 'basic', 'pro', 'admin']}. Same for 'model', 'type', 'role'.