gentle-pi has 9 tools with mixed quality. Naming is generally verb-based (read, bash, grep, find, ls, edit, write, codegraph, ask_user_choice), but several tools lack proper input schema documentation. The codegraph tool has a well-defined schema with constraints (operation enum, query minLength/maxLength, limit min/max). However, 5 of 9 tools (read, bash, grep, find, ls, edit, write) show minimal schema detail in the provided source, properties are present but lack type constraints, minLength, maxLength, or enum values. Descriptions are present but brief (10-50 chars for most tools). The bash tool is particularly concerning: it accepts arbitrary shell commands with no validation, sanitization, or safety constraints. Error handling is absent, no recovery guidance, no categorization of errors as retryable vs fatal. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk levels (IRREVERSIBLE for bash, WRITE for edit/write). Output schemas are not documented.

• Add comprehensive input schema constraints to read, bash, grep, find, ls, edit, write: specify path format (string, minLength, maxLength, pattern for safe paths), command/pattern length limits, and enum values where applicable.
• Add tool annotations: mark bash and write as destructiveHint=true, edit as destructiveHint=true, read/grep/find/ls as readOnlyHint=true. This enables agents to reason about safety.
• Document output schemas for all tools. E.g., read returns {content: string, path: string, size: number}; bash returns {stdout: string, stderr: string, exitCode: number}; grep returns {matches: [{line: number, text: string, file: string}], totalMatches: number}.
• Implement input validation and sanitization for bash: reject commands containing dangerous patterns (rm -rf, >, |, &&, ||, ;). Return actionable errors: 'Command contains pipe operator, use separate grep/find calls instead.'
• Add error recovery guidance: 'File not found at /path/to/file. Try ls() to list available files in the directory.' Categorize errors as retryable (timeout, ECONNREFUSED) vs fatal (permission denied, invalid path).