Akemon exposes two tools with STDIO-only transport. Both tools have descriptions and Zod-based schema definitions visible in src/mcp-server.ts, but the schemas exhibit critical gaps: `require_human` and `collaborative` parameters accept union types (boolean | string) without clear enum constraints or format documentation; the `call_agent` tool has no documented output schema; both tool descriptions lack actionable guidance on error recovery and are overly brief for LLM decision-making (the submit_task description at ~180 chars is reasonable, but call_agent at ~150 chars lacks context on when to prefer it over alternatives). Neither tool includes parameter-level descriptions for all fields, `require_human` and `collaborative` descriptions are present but vague on how string values are interpreted. No input validation rules, enums, or ranges are specified. Error handling is minimal: the code returns generic error messages like '[error] Failed to call agent' without guidance on retryability or next steps. The tool names are adequate (verb_noun form), but parameter naming could be clearer (what string values are valid for boolean|string union types?). No tool annotations (readOnlyHint, destructiveHint, idempotentHint) are present.

• Replace union types (boolean | string) with explicit enums. If require_human accepts 'true', 'false', or a username, define it as z.enum(['true', 'false', 'username']) or use a discriminated union with clear cases.
• Document output schema for call_agent: specify that it returns { content: [{ type: 'text', text: string }], isError?: boolean }. LLMs need to know whether to extract the text field or check isError.
• Add tool annotations: mark both tools with { destructiveHint: true } since they modify state (spawn executions, invoke agents). This signals to LLMs that retries may cause duplicate side effects.
• Expand call_agent description to clarify decision logic: 'Use for time-sensitive queries where you need a response before proceeding. For background/batch tasks, use submit_task. call_agent blocks; submit_task is async and handled by the agent end-to-end.'
• Add parameter constraints in descriptions: 'agent: name of a registered agent (alphanumeric, 3-50 chars). If unsure, ask the user or check available agents.' Similarly for task: 'natural language task description (1-2000 chars, no special escaping needed)'.
• Improve error messages to guide recovery: instead of '[error] Failed to call agent "target"', return '[error] Agent "target" not reachable: X. Try: (1) verify agent name is correct, (2) check if agent is online, (3) try submit_task instead for async execution.' Use isError: true to signal retryability.
• Add output field documentation in the handler or as inline comments: 'Returns { content: [{ type: "text", text: string }], isError?: boolean }. For subsequent chaining, extract text from content[0].text.'