The server defines 2 tools with explicit schemas and descriptions visible in src/tools/index.ts. Both tools have properly structured input schemas with type definitions and property descriptions. However, there are significant gaps in parameter documentation, no output schemas are documented, error handling is minimal, and no tool annotations are present. The tool naming follows the verb_noun pattern (fetch-embeddings, list-user-files) which is good, but parameter descriptions are inconsistent in detail and depth. The tools are simple read-only operations with basic error handling that returns unstructured error messages without actionable recovery guidance.

• Document output schemas for both tools. For fetch-embeddings, specify that it returns structured content with fields like [{ file_id, content, score }]. For list-user-files, specify the UserFile object structure and pagination fields.
• Enhance error messages with recovery hints. E.g. 'Failed to retrieve embeddings: file not found. Verify the file_id using list-user-files first.'
• Add bounds and details to numeric/enum parameters. E.g. 'limit: Number of files to fetch (1-100, default 10)' and 'order_dir: Sort by file creation date (asc=oldest first, desc=newest first)'.
• Add tool annotations via MCP. Mark both tools with readOnlyHint: true since they only read data and are idempotent.
• Refactor fetch-embeddings response to return structured objects. Instead of joining content as a string, return an array of { file_id, content, score? } objects.
• Filter list-user-files response. Return only { file_id, file_name, created_at } unless the LLM explicitly needs team_id. This reduces token bloat and focuses the response on actionable data.
• Add pagination cursors or total_count to list-user-files response so the LLM knows if more results exist and can plan subsequent calls.