Auggie MCP defines 2 tools with visible schemas and descriptions. However, the server has critical gaps in parameter documentation, output schema clarity, and error handling guidance. Tool naming is reasonable but descriptions lack depth on WHEN to use each tool and WHAT dependencies exist. Parameters lack descriptions for most fields (workspace_root, model, rules_path documented only in ask_question; missing entirely for others). Output schemas are partially documented in code comments but not formally exposed. No enum constraints, no validation error messages. The implement tool accepts sensitive operations (git branch checkout, commit) with only a 'dry_run' safety gate, no explicit permission checks or audit trail. STDIO transport caps the protocol readiness, limiting overall usefulness.
Tools (2)
ask_questionread onlyauthsource verified65/100
Q&A over a repository using Auggie's context engine.
implementwriteauthsource verified55/100
Implement a change in the repo. Optionally commit.
Missing parameter descriptions for critical fields in both tools. 'workspace_root', 'model', 'rules_path', 'timeout_sec', 'stream' lack descriptions in the implement tool. Parameter 'scope' (array) has minimal documentation. LLMs cannot determine when to use these parameters without explicit descriptions.
Output schema not formally documented in tool registration. ask_question returns {answer, usage} and implement returns ImplementResult (TypedDict with summary, files_changed, diff, committed, commit_sha, usage), but these are only visible in Python code comments, not in the MCP tool schema. LLMs must infer output structure.
Destructive tool (implement) lacks permission gates and audit trails. The tool can modify git state (checkout branch, commit changes) with only a 'dry_run' boolean flag. No explicit permission checking, no audit logging of who called what. No confirmation/approval step before irreversible operations.
implement
Recommendations
Add descriptions to every parameter in both tools. For workspace_root: 'Root directory of the repository to query. Defaults to current working directory. Must be a valid path to a git repository.' For model: 'Optional AI model name to use (e.g., claude-3-opus). If omitted, uses Auggie default. Valid models depend on your AUGMENT_API_TOKEN permissions.'
Formally document output schemas in MCP tool registration. Instead of returning dict/TypedDict, explicitly register the response structure: {type: 'object', properties: {answer: {type: 'string'}, usage: {type: 'object', properties: {duration_ms: {type: 'integer'}}}}}
Add enum constraint to 'model' parameter with list of known valid models, or update description with pattern hint like 'Model name as string; common values: claude-3-opus, gpt-4, gemini-pro.'
Bound timeout_sec: 'Integer timeout in seconds (5 - 3600). Default 240 for ask_question, 600 for implement. Prevents runaway calls.'
Add explicit error handling for missing dependencies. Catch FileNotFoundError when spawning 'auggie' command and return actionable message: 'Auggie CLI not found. Install with: pip install augment-cli. Or set AUGMENT_API_TOKEN environment variable for authentication.'
Implement audit logging. Before executing implement (especially with commit_message set), log: '{timestamp} | {caller_id} | implement called with workspace={workspace_root}, branch={branch}, dry_run={dry_run}, commit={commit_message}'
Add confirmation/approval gate for non-dry-run operations. If commit_message is provided and dry_run=false, require multi-round-trip: return {status: 'pending_confirmation', action: 'commit', details: {...}, request_user_approval: true} and wait for user confirmation before executing git commit.
Error handling provides minimal recovery guidance. When _run() returns non-zero exit code, the tool raises RuntimeError with command and stderr/stdout clipped to 2000 chars. No categorization of error types (retryable vs fatal), no suggestions for next steps, no parsed error messages that guide LLM correction.
No enum constraints on constrained inputs. 'model' parameter accepts free-form string with no enum of valid models. 'stream' is a boolean but not explicitly documented as controlling output format behavior. No validation prevents hallucinated model names.
Tool descriptions do not state WHEN to call each tool or dependencies. 'Q&A over a repository using Auggie's context engine' does not explain when to choose ask_question vs implement, or that implement may require Auggie to be installed and AUGMENT_API_TOKEN set. No discovery hints.
Timeout parameters lack constraints. Both tools accept 'timeout_sec' as integer with no min/max specified. An LLM could pass timeout_sec=1000000, causing indefinite hangs. No documented bounds or recommended values.
implement tool accepts 'scope' as array of strings with only 'Optional list of files to limit edits to' as description. No validation, no examples of valid file paths, no error message if scope paths do not exist.
implement
Split tool descriptions to include WHEN to call: ask_question: 'Use this to query an existing repository for information without modifying code. Faster than implement, useful for understanding before making changes.' implement: 'Use this to generate and apply code changes. Can optionally create git branches and commits. Always runs in dry_run mode by default for safety.'
Add dependency documentation. In tool descriptions or a server-level notes section: 'Requires Auggie CLI >= 1.0. Set AUGMENT_API_TOKEN environment variable or authenticate with `auggie login` before calling these tools.'
Enhance error recovery. Instead of raw exit codes, parse stderr for known Auggie error patterns (permission denied, workspace not found, timeout) and return structured error: {error_type: 'workspace_not_found', message: 'Workspace ... does not exist', suggestions: ['Check workspace_root path', 'Run from a git repository root']}
For implement tool, document scope parameter with example: 'scope: Optional list of file paths to limit edits to. Example: ["src/main.py", "tests/test_main.py"]. If omitted, Auggie may modify any file matching its rules.'
Add idempotent operation hint for ask_question (safe to call repeatedly with same input, no side effects) and destructive hint for implement (modifies files, may commit changes).