Pythia has 20 tools with basic schemas and descriptions, but significant gaps limit production readiness. All tools have descriptions (10-100 chars, mostly adequate), and input schemas are present with type definitions. However, output schemas are entirely undocumented, LLMs cannot predict what fields to expect from responses, forcing guesswork on downstream tool chaining. Parameter descriptions are minimal (often just restating the name). Error handling is absent, no guidance on retryability, user-fixable vs fatal errors, or recovery paths. No tool annotations (readOnlyHint/destructiveHint) despite clear risk stratification in the data. The 'apply' and 'journal' tools handle irreversible writes but lack confirmation/dry-run patterns. Tool composition is reasonable (each does one thing), but naming could be more consistent (e.g., 'ls' vs 'list', 'cols' vs 'columns'). Security is a concern: 'sql' and 'apply' accept arbitrary input with minimal validation guidance.

• Document output schemas for all tools. Specify field names, types, and whether results are paginated. E.g., 'src' should return {source: string, line_count: integer, last_modified: ISO8601_date}.
• Add tool annotations to MCP definitions: mark 'apply', 'policy', 'journal' as destructiveHint=true; mark all read-only tools as readOnlyHint=true; mark idempotent tools (e.g., 'check') as idempotentHint=true.
• Formalize the confirmation pattern for 'apply' and 'journal restore': document the preview step (returns snapshot + confirmation token), then the apply step (requires token). Add a dry-run mode that shows impact without executing.
• Add error recovery guidance to tool descriptions. E.g., 'sql' should say: 'Returns error code 2 if statement is not SELECT/WITH. Use 'apply' for write operations.' For 'apply', document what to do if verification fails (rollback guidance).
• Standardize naming: rename 'ls' to 'list_objects', 'cols' to 'list_columns', 'grep' to 'search_source'. Use verb_noun convention consistently across all 20 tools.