Two tools with basic descriptions and partially visible schemas. analyze_repository has a clear description (81 chars) and defined input parameters (repo_path, max_depth), but output schema is not documented in the provided code. read_file has a basic description (93 chars) and clear inputs (repo_path, file_path), but no output schema visible. Neither tool has documented return types or error handling guidance. Parameter descriptions are present and adequate (repo_path, file_path, max_depth), meeting baseline minimums. However, there is no evidence of schema validation, error categorization, or recovery guidance in the source code. Both tools operate in a read-only context (no destructive operations), which reduces security risks. The code shows path validation logic (_is_safe_path, symlink checks, gitignore handling) but these defensive checks are not surfaced in tool descriptions to guide the LLM.

• Document output schemas for both tools. Specify that analyze_repository returns a FileStructure object with fields {path: string, type: 'file'|'directory', size?: number, children?: FileStructure[], summary?: {file_count, dir_count, total_size}}. Specify that read_file returns {content: string, language: string, line_count: number, truncated: boolean}.
• Add error handling guidance to descriptions. E.g., 'Returns error if repo_path does not exist, is not readable, or contains a symlink. Returns error if file_path attempts directory traversal outside repo_path. Returns truncation notice if file exceeds 1MB or 1000 lines.'
• Specify input constraints for max_depth (e.g., '1-20, defaults to 3') and for file_path (e.g., 'relative path, must not contain ../ or absolute paths'). Validate and return actionable errors if constraints are violated.
• Add a discovery/validation tool (e.g., validate_repo_path or list_repos) so agents can confirm a repository path is accessible before attempting analysis.
• Document when analyze_repository returns summaries vs. full children lists (at depth limit or when MAX_CHILDREN exceeded). Help LLMs understand when to adjust max_depth.
• Return structured JSON from both tools, not formatted strings. Let the client format for display. include_chaining_ids pattern: if an agent calls analyze_repository and later needs to read files, the response should include file paths the agent can pass directly to read_file.