Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
The BorgOS MCP server has significant definition quality gaps. While 14 tools are present with basic schemas and descriptions, most descriptions are too brief (10-50 chars vs. the 194-char baseline), parameter descriptions are sparse or missing for many tools, and critical tools expose dangerous destructive capabilities (execute_command, delete_file, deploy_project) without adequate error handling or permission guidance. Tool naming follows verb_noun convention adequately (list_*, get_*, scan_*, deploy_*, execute_*, analyze_*, read_*, write_*, delete_*, move_*, search_files), but composition issues exist: execute_command and the filesystem tools (read_file, write_file, delete_file) are too low-level for a project management system and invite prompt injection risks. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) are present despite the risk profile. Output schemas are largely undocumented, no tool explicitly describes its return structure. Error handling is absent: no recovery guidance, no error classification, no confirmation patterns for irreversible operations. Security concerns are acute: execute_command accepts arbitrary shell commands with no input sanitization noted, and delete_file with recursive=true can destroy directory trees. The schema quality varies: some parameters lack type information or descriptions (e.g., 'environment' object in deploy_project has no field-level schema), and several tools have no documented output structure.
Tools (14)
analyze_coderead only50/100
Analyze code quality and suggest improvements
delete_filedestructivesource verified58/100
Delete a file or empty directory
deploy_projectirreversible50/100
Deploy a project to a specific port
execute_commanddestructive45/100
Execute a system command
get_errorsread only50/100
Get recent error logs
get_project_detailsread only50/100
Get detailed information about a project
list_deploymentsread only50/100
List all deployments
list_directoryread onlysource verified63/100
List contents of a directory with detailed information
execute_command accepts arbitrary shell input with no sanitization documentation or validation guidance. Exposes the system to command injection attacks if the LLM is tricked into passing malicious payloads. No error handling or timeout specification.
delete_file with recursive=true can recursively delete directory trees. No confirmation pattern, no dry-run option, and no description warning of irreversibility. Agents can accidentally destroy entire project directories.
deploy_project marked as IRREVERSIBLE but has no confirmation pattern, no dry-run mode, and no recovery guidance. Agents can deploy without understanding consequences. The 'environment' parameter is an object with no field-level schema.
deploy_project
Recommendations
Add tool annotations (readOnlyHint, destructiveHint, idempotentHint) to all 14 tools. Mark execute_command, delete_file, write_file, deploy_project, and scan_project as destructive. This enables LLMs to reason about safety.
Expand all tool descriptions to 100-250 characters. Include WHEN to use each tool, what structure it returns, and any prerequisites. Example for list_projects: 'List all projects in BorgOS, returned as an array with project_id, name, status, and last_scanned timestamp. Use this to discover available projects before calling get_project_details or scan_project.'
Document complete output schemas for all tools. Define return type (object, array, string, etc.), required fields, field types, and descriptions. Example: 'Returns an array of project objects with fields: {project_id: integer, name: string, status: enum[active|archived|error], last_scanned: ISO8601 string, error_count: integer}'.
Add parameter descriptions for all undocumented parameters. For 'environment' in deploy_project, specify: 'Object with environment variable key-value pairs. Keys must be valid env var names (alphanumeric and underscore). Values are strings. Example: {"NODE_ENV": "production", "LOG_LEVEL": "info"}'. For 'severity' in get_errors, specify enum values: 'Filter by severity level (one of: debug, info, warning, error, critical).'
Implement a confirmation pattern for irreversible operations. For deploy_project and delete_file, add optional 'confirm=true' parameter or return an intermediate response requiring user approval before executing. Document this in the tool description.
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Descriptions are consistently too brief (10-50 chars vs. 194-char baseline). Most tools lack context on WHEN to use them, prerequisites, or side effects. Example: 'List all projects in BorgOS' (30 chars) lacks guidance on structure returned or common follow-up actions.
Output schemas are not documented for any tool. LLMs cannot determine what fields to expect, forcing them to guess or make assumptions about return structures. This violates the 100% A+ baseline of documented return types.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) present despite high-risk tools. execute_command, delete_file, write_file, and deploy_project are destructive but not marked as such. LLMs cannot distinguish safe reads from dangerous writes without explicit hints.
Parameter descriptions are often missing or minimal. 'environment' in deploy_project is marked required=false but has no description of expected keys/values. 'pattern' in search_files needs format guidance (regex vs glob). 'severity' in get_errors needs enum values.
No error handling or recovery guidance. Tools do not document what errors can occur, whether they are retryable, or what the LLM should do next. Example: execute_command could fail with permission denied, command not found, or timeout, none are documented.
Filesystem tools (read_file, write_file, delete_file, list_directory, move_file, search_files) are too low-level for a BorgOS project management context. They are powerful but lack safeguards and invite accidental data loss. Consider wrapping them with higher-level project-specific abstractions.
No documented permission model or scope declarations. Tools like delete_file and deploy_project should declare required permissions (e.g., 'write:projects', 'deploy:production'). Without this, agents cannot be configured with least-privilege access.
Parameters like 'limit' (get_errors, search_files) and 'recursive' (list_directory, delete_file) lack bounds or validation. What happens if limit=1000000 or recursive is not a boolean? No constraints are documented.
get_errorssearch_fileslist_directorydelete_file
Add input validation and sanitization guidance for execute_command. Document what commands are allowed/blocked, what environment variables are available, and timeout limits. Or consider removing this tool entirely if it's too dangerous, expose higher-level domain-specific operations (build_project, test_project, etc.) instead.
Add error handling and recovery guides. Document what can go wrong for each tool and what the LLM should do. Example for execute_command: 'Errors: (1) Command not found, suggests a typo or missing tool. Ask the user to verify. (2) Permission denied, suggest running with elevated privileges if authorized. (3) Timeout after 30s, command is too slow or stuck. Suggest killing it or simplifying the command.'
Add permission/scope declarations to high-risk tools. Example: 'Requires scope: write:projects, deploy:production. This tool can only be used if the agent has explicit deploy authorization.'
Apply bounds and constraints to numeric/boolean parameters. For 'limit' parameters, specify 1-1000 range. For 'recursive' flags, clarify behavior: 'If true, recursively processes all subdirectories. Warning: this can be slow on deep directory trees.' For 'mode' in write_file, enforce enum: 'File write mode (one of: w for overwrite, a for append).'
Consider refactoring filesystem tools into project-scoped versions. Instead of generic read_file, offer read_project_config_file, read_project_code, read_deployment_log. This reduces accidental misuse and guides LLM selection.
Add parameter constraints and format guidance. For 'pattern' in search_files, clarify: 'Glob pattern (e.g., *.py, src/**/*.js). Use * for any characters, ? for single character, ** for recursive directories.' For 'project_id', specify: 'Integer identifier of the project (e.g., 42). Obtain via list_projects.'
Document idempotency and side effects. Example for scan_project: 'Idempotent: calling scan_project multiple times with the same project_id is safe, it will scan again and return updated results, without duplicating data.' For deploy_project: 'Non-idempotent: each call deploys a new instance. Calling twice will create two deployments.'
Add pagination support and result limits to list_* tools. Example for search_files: 'Returns up to max_results (default 100) matching files. If more results exist, include next_cursor in response and support pagination via start_cursor parameter.'
Include chaining IDs in responses. If deploy_project returns a deployment_id, and subsequent tools need team_id or project_id, include all three in the response to enable downstream tool calls without extra lookups.