The server defines 17 tools with schemas visible in src/ensoul/tool_schema.py. All tools have names, descriptions, and input schemas. However, there are significant gaps in schema completeness, parameter descriptions, and output schema documentation. Descriptions are present but brief (averaging ~50-80 chars, below the 194-char production baseline). No tool has documented error handling, recovery guidance, or output schemas. Many parameters lack descriptions entirely or have minimal detail. The tool set mixes domain-specific concerns (file I/O, git, bash execution) with organizational/agent-management tools (delegation, meetings, pipelines), which is reasonable for a multi-agent framework. However, the definitions do not meet production-grade standards for parameter validation, error categorization, or downstream tool composability.
Output schemas are not documented for any tool. LLMs cannot infer what fields to expect in responses, preventing them from planning downstream calls or extracting data for follow-up steps.
Parameter descriptions are missing or minimal across all tools. Many parameters have descriptions under 20 characters (e.g., 'args' in git tool is '额外参数' ~8 chars), violating the requirement that every parameter have a non-empty, descriptive annotation.
Document the output schema for every tool as a JSON Schema object. For example, file_read should specify: {type: 'object', properties: {content: {type: 'string'}, line_count: {type: 'integer'}}, required: ['content']}. This enables LLMs to plan chained calls and extract structured data.
Expand tool descriptions to 150 - 250 characters, following the production baseline. Include: (1) what the tool does, (2) when to use it vs. similar tools, (3) any prerequisites or side effects. Example for delegate: 'Synchronously assign a task to a named employee and wait for completion. Use when the result is needed immediately (e.g., sequential task dependencies). For fire-and-forget tasks, use delegate_async instead.'
Add non-trivial descriptions to all parameters. For 'args' in git, replace with: 'Additional arguments to pass to the git subcommand (e.g., '--pretty=fuller' for log, '--stat' for diff). See git documentation for valid options per subcommand.'
Validate and document constraints for numeric and string parameters. For bash timeout: add min=1, max=3600 to the schema and note '1 - 3600 seconds; tasks exceeding this limit will timeout and return an error.' For git args, add a pattern constraint: '^[a-zA-Z0-9\s\-._=/]+$' to prevent injection.
Add error handling guidance to bash, git, and file_write descriptions. Example for bash: 'Returns stdout/stderr. Non-zero exit codes indicate failure, use these to determine if a retry is safe or if user input is needed. Common errors: command not found (install missing tools), permission denied (check file permissions), timeout (increase timeout or break into smaller commands).'
Tool descriptions are too brief (averaging ~50 - 80 chars vs. the 194-char production baseline). Descriptions lack guidance on when to select each tool vs. similar alternatives (e.g., delegate vs. delegate_async, delegate_chain vs. route). This forces LLMs to guess tool selection based on name alone.
No error handling or recovery guidance. Tools like bash and git can fail in many ways (command not found, permission denied, merge conflicts) but tool definitions do not explain what errors are possible, whether they are retryable, or what the LLM should do next.
Bash and file_write tools are destructive (IRREVERSIBLE and WRITE risks) but lack dry-run or confirmation-step patterns. An LLM could accidentally delete files or execute harmful commands without a safeguard.
Parameter 'timeout' in bash tool (default 300s) and array parameter 'steps' in delegate_chain have no min/max bounds or validation constraints. LLMs could pass arbitrary values (e.g., timeout=999999) without guidance.
Tool 'route' accepts 'template' parameter (string) and 'overrides' parameter (object) but does not document what valid template names are, what structure 'overrides' must have, or what role keys are allowed.
Delegation tools (delegate, delegate_async, delegate_chain) accept 'employee_name' but do not document how names are resolved, whether fuzzy matching is available, or what happens if the name does not exist.
Tool names use underscores (file_read, list_tasks) which is idiomatic, but descriptions and parameter names are in Chinese, creating a mixed-language interface. This may confuse LLMs trained primarily on English patterns.
all
Implement confirmation or dry-run patterns for destructive tools. For bash, add an optional 'dry_run' boolean parameter (default false). When true, echo the command without executing. For file_write, document that the tool will fail if the file exists and ask the user to confirm overwrite via a separate 'confirm' step.
Document template names and role keys for the route tool. Add a description: 'Uses a predefined route template (e.g., "code-review", "content-approval"). Provide overrides to map roles (e.g., {"reviewer": "alice", "approver": "bob"}) to specific employee names. Call list_templates() first to see available options.'
Add a discovery tool (e.g., list_templates, list_employees) to help LLMs self-discover valid values for delegation targets and templates. This reduces the need for hardcoded assumptions.
Document task ID format and lifetime. For check_task and check_meeting, clarify: 'Returns the current state of task ID <ID>. Task results are available for 7 days after completion; older tasks may not be found.'
Standardize parameter naming. Decide on English or Chinese and stick with it consistently. If Chinese is required for localization, use English in the tool/parameter names and provide Chinese translations in descriptions.
Add 'idempotentHint' and 'destructiveHint' annotations to tool definitions (MCP tool annotations). For file_write: set destructiveHint=true if overwrite is possible. For check_task and list_tasks: set readOnlyHint=true. This helps MCP clients enforce permission gates and warn users of destructive actions.