Two tools with basic but incomplete definitions. Both tools have descriptions and input schemas, but descriptions are minimal (around 100 chars each), missing critical guidance on prerequisites, return structure, and error recovery. Parameter descriptions are minimal. No output schemas documented. No parameter validation hints or error handling guidance. Tool names follow verb_noun pattern correctly. No tool annotations. Schemas present but lack depth and LLM optimization.
Minimal parameter descriptions: 'repo_url' only says 'The URL of the Git repository', no hints on format, accepted protocols (https vs ssh), or error recovery if clone fails. 'file_paths' array lacks guidance on depth limits, path traversal risks, or maximum file count.
No output schema documented. LLMs cannot plan downstream operations or extract structured data. git_directory_structure returns 'tree format' but doesn't specify line-by-tree structure, encoding, or max depth. git_read_important_files returns JSON object of file paths → contents but no type hints on content (string, binary, truncated?), max file size, or encoding.
No error recovery guidance. Errors return plain text (e.g., 'Error: Failed to clone repository: ...') with no actionable hints for the LLM. No indication whether the error is retryable, user-fixable (bad URL?), or fatal. LLMs cannot self-correct or adjust strategy.
Recommendations
Expand parameter descriptions: 'repo_url: Git repository URL (must be valid https:// or ssh:// clone URL; will be cloned to a temporary directory; clone may fail if repo is unreachable, too large (>500MB), or requires authentication). Accepted formats: https://github.com/user/repo, git@github.com:user/repo.git'.
Document output schema explicitly in tool descriptions: 'Returns a text tree structure (lines with ├──, └──, │ characters) showing directory names and nesting. Max depth: 100. Excludes .git/ directory and hidden files. Total output capped at 100KB.'
Add error recovery guidance: On clone failure, suggest 'Verify repo URL is correct and publicly accessible. If private, authentication is not yet supported, contact admin.' On file read failure, suggest 'File may not exist or is too large (max 10MB). Verify path is relative to repo root.' On timeout, suggest 'Repo may be very large or network is slow. Try a smaller file subset or smaller repo.'
Rename 'git_read_important_files' to 'read_files_from_repo' or 'fetch_repo_files' for clarity. If you want to hint that common important files are README/LICENSE/package.json, add to description: 'Useful files: README.md, package.json, Dockerfile, requirements.txt, setup.py, .github/workflows/*.yml'.
Add input constraints to descriptions: 'repo_url: max 2048 chars, file_paths array: max 50 items, each path max 1024 chars. Paths must be relative (no ../ traversal allowed). Binary files (images, archives) are not supported, returns 'binary file' placeholder.'
No input validation constraints or limits. No hint on max repo size, max file count, max file size, or path traversal protection. LLMs could pass extremely large repos or malicious paths; tool silently processes them with unpredictable behavior.
Tool name 'git_read_important_files' is vague. 'Important' is subjective, does the LLM know which files are important? Better names: 'read_files_from_repo', 'fetch_repo_files', or 'read_files' (if git context is implicit). Current name may cause LLMs to mis-estimate what files they can retrieve.
No tool annotations (readOnlyHint, idempotentHint). Both tools are read-only and idempotent, but MCP annotations are missing. Agents cannot infer safety properties without explicit hints.
git_directory_structuregit_read_important_files
Add tool annotations in ListToolsRequestSchema response: for both tools, add 'readOnlyHint: true' and 'idempotentHint: true' to signal they are safe to retry.
Document rate limits and timeouts: 'Git clone timeout: 60s. File read timeout: 10s. Max concurrent clones: 5. Large repos (>100MB) may timeout, try fetching specific files instead of full structure.'
Return structured JSON for both tools (not just text tree). For git_directory_structure, return {files: [{name, type: 'file|dir', size, depth}], totalFiles, totalDirs, truncated} so LLMs can reason about structure. For git_read_important_files, return {results: [{path, content, encoding, sizeBytes, readError?: string}], failedPaths: [...], totalProcessed} so partial failures are explicit.