Seshat has 25 tools with basic naming and descriptions, but critical gaps undermine quality. Tool names follow verb_noun convention (bash, edit_file, read_file), which is good. However, descriptions are extremely brief (10-50 chars) and lack actionable context for LLM selection. Most critically: NO input schemas are visible in the provided source code. Tool definitions appear as string names in tool_names.go with descriptions, but actual JSON Schema definitions with parameter types are not shown. This is a hard blocker, without schemas, LLMs cannot validate inputs or understand parameter constraints. Error handling is minimal; no recovery guidance or categorization. Security concerns: bash and agent tools are high-risk but lack permission gates or dry-run patterns. Composition is reasonable (tools are single-purpose), but many tools lack pagination support despite handling lists (list_directory, grep, web_search).

• Add complete JSON Schema definitions for all 25 tools. Each parameter must have type (string, integer, boolean, array, object), description (50-150 chars), and constraints (enum, pattern, minLength, maxLength, minimum, maximum). Example: {"command": {"type": "string", "description": "Bash command to execute. Avoid destructive commands (rm, dd, mkfs) without explicit user confirmation.", "minLength": 1, "maxLength": 10000}}
• Expand tool descriptions to 100-200 characters. Include WHAT the tool does, WHEN to use it (vs similar tools), and key constraints. Example for bash: 'Execute bash commands on the local system. Use for file operations, system queries, and automation. Avoid destructive commands without user confirmation. Returns stdout, stderr, and exit code.'
• Add pagination to list/search tools: limit (1-100, default 20), offset (0+), and return total_count or next_cursor. Document max result limits in descriptions. Example: 'Returns up to 50 matches; use offset for pagination.'
• Implement permission gates for bash, remove_file, agent, and job_kill. Verify caller has required scopes (e.g., 'exec:bash', 'write:filesystem', 'spawn:agent') before execution. Return 403 Forbidden with required scope if denied.
• Add error handling guidance to all tools. Categorize errors as retryable (network timeout, rate limit), user-fixable (invalid path, missing file), or fatal (permission denied). Return structured errors: {"error": "file_not_found", "path": "/tmp/missing.txt", "suggestion": "Check the path or use list_directory() to find available files."}