file-ai demonstrates solid schema coverage with Zod-based input validation and clear parameter descriptions. All 5 tools have explicit descriptions (194 - 250 chars, within baseline 34 - 392 range) and typed parameters with constraints. However, output schemas are not documented, LLMs cannot predict response structure. Tool names follow verb_noun convention (doc_analyze, doc_read, doc_search, doc_context, doc_list_formats) but lack action clarity for discovery. Error handling is absent, no recovery guidance, retryability classification, or actionable error messages. No tool annotations (readOnlyHint, idempotentHint) despite all tools being read-only. Parameter descriptions are adequate but lack format/range details (e.g., 'path' should specify absolute vs relative, file size limits). Missing dependency hints and mutual exclusivity documentation (e.g., indexId vs path in doc_read, doc_search, doc_context).

• Document output schemas for all tools. Example for doc_analyze: 'Returns {profile: {indexId, filename, format, ...}, outline: [...], anchors: [...], chunks: [...], resources: [...]}'.
• Add error handling with recovery guidance. Example: 'If file not found, check path spelling. If parsing fails, try refresh=true. If out of memory, reduce chunkSize.'
• Clarify mutual exclusivity in doc_read, doc_search, doc_context. Example: 'Either indexId (preferred, uses cache) or path (triggers analyze). If both provided, indexId takes precedence.'
• Add tool annotations via inputSchema metadata. Mark all tools with readOnlyHint=true and idempotentHint=true to signal safety to agents.
• Specify parameter constraints in descriptions. Example: 'path: absolute or relative file path (max 4096 chars, must exist)' and 'limit: 1 - 1000 results (default 20)'.