CodeSight exposes 6 tools via FastAPI HTTP server. All tools have names and descriptions present, and input parameters are typed with JSON Schema. However, descriptions are inconsistent in quality and depth, several parameters lack descriptions entirely, and output schemas are not documented in the tool definitions. Error handling is minimal, tools do not guide LLMs on recovery paths. The server stores API keys server-side (good security posture) but lacks tool annotations (readOnlyHint/destructiveHint) despite having mixed risk profiles. Per-tool analysis: search and ask have solid query/top_k/file_glob/source parameters but output schema is undocumented; index lacks a description of what force_rebuild actually triggers and no warning about destructive behavior; status, health, and config are minimal stubs with no parameters and trivial descriptions.

• Document output schemas for all tools. E.g., search returns {results: [{id, title, score, source, file, snippet}], total_count, next_cursor}, ask returns {answer: string, sources: [{file, chunk}]}. Include this in the tool definition or add a 'returns' field.
• Expand index description: 'Rebuild the document search index from the documents directory. force_rebuild=true deletes the existing index and rebuilds from scratch, this is irreversible and may take several minutes on large corpora. Omit force_rebuild or set to false for an incremental update.'
• Add tool annotations: mark search/ask/status/health/config as readOnlyHint=true; mark index as destructiveHint=true (when force_rebuild=true) or idempotentHint=true (when force_rebuild=false). This signals to agents which tools are safe to retry.
• Improve status/health/config descriptions. E.g., status: 'Returns indexing progress, repository metadata (document count, last indexed time, index size), and any active indexing operations.' health: 'Checks server availability and configuration (auth required, LLM backend in use).'
• Add parameter descriptions for source enum in search/ask: 'Optional source filter. Currently supports "holus" for Holus-imported document collections; omit for all sources.'
• Implement error messages with recovery hints. E.g., index tool: on IndexInProgressError, return 'Index operation already in progress. Try again in 30 seconds, or call status() to monitor progress.' on missing documents dir: 'Documents directory not found at /data. Mount your documents via Docker -v /path/to/docs:/data:ro.'