Static source inference · medium confidence · detected: Sampling, Logging
Deprecated protocol patterns detected
Summary
The sofos-code server defines 17 tools with varying quality. Naming is good (verb-noun patterns like read_file, write_file), but schema documentation and parameter descriptions are minimal. Most tools show only basic parameter names and types without rich descriptions explaining WHEN to use them, WHAT constraints apply, or HOW to interpret results. No output schemas are visible in the provided code. The tool_name.rs file shows a type-safe enum and read-only classification logic, but this is infrastructure, not definition quality. Error handling, security context, and composition patterns are not evident from the source. No input validation rules, examples, or per-parameter guidance visible.
Parameter descriptions are missing or trivial. Every parameter is documented only with a name and type (e.g., 'path': {'type': 'string', 'description': 'Path to the file to read'}). Descriptions lack guidance on format constraints, ranges, enum values, or when to use alternatives. Per pattern:tool-description, 100% of A+ tools have rich parameter descriptions explaining FORMAT, RANGE, and ALLOWED VALUES. Current descriptions are 5-10 characters when they should be 50-150.
No output schemas documented. The provided code defines tool inputs only; no output/response schemas are visible. LLMs cannot know what fields to expect from tool results, forcing them to parse unstructured responses and guess at field names. This violates pattern:response-shaper and pattern:tool.
Recommendations
Expand all tool descriptions from current 10-35 chars to 100-200 chars. Each should state: WHAT the tool does, WHEN to use it instead of similar tools, and WHAT constraint or risk applies. Example: 'Execute a single bash command and return the output. Use for short scripts; prefer write_file + execute_bash for complex multi-step operations. Commands run with user permissions; ensure input is trusted to prevent injection attacks.'
Add comprehensive parameter descriptions. For each parameter, document: (1) expected format/type, (2) allowed values or enum options, (3) min/max range if numeric, (4) example if helpful. Example for 'command' param: 'Bash command to execute (string, max 5000 chars). Must be a valid bash command; variables like $HOME are interpolated. Avoid passing user input directly; use quoting and validation.'
Document output schemas for every tool. Define response structure, field types, and semantics. Example for read_file: 'Returns {"content": string, "size_bytes": number, "encoding": string (utf-8|binary), "error": string|null}. If file does not exist, returns {"error": "ENOENT", "path": string}.'
Add error classification and recovery guidance. Example: 'If path is not found, try list_directory on the parent path to confirm it exists. If permission denied, verify read access for the current user. Errors are retryable if the file becomes available.'
Distinguish edit_file and morph_edit_file. Document which algorithm each uses, when one is preferred over the other, and what format expectations differ. Or consolidate into one tool with an optional 'algorithm' parameter.
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Sampling (deprecated) - integrate directly with the LLM provider API
Irreversible and destructive tools (execute_bash, delete_file, delete_directory) lack error recovery guidance and confirmation patterns. No indication that agents can dry-run or see a preview before executing. Per pattern:confirmation-request, destructive operations should offer a confirmation step to prevent catastrophic errors.
execute_bash accepts free-form command strings with no validation rules, constraints, or security guidance visible. Per pattern:tool-gateway, all agent-provided input must be treated as untrusted and validated against command injection, path traversal, and privilege escalation. No documentation of what commands are allowed, blocked, or rate-limited.
No error classification or recovery guidance visible. Pattern:recovery-guide requires error responses to tell the LLM what to do next (e.g., 'User not found. Try search_users() with a partial name.'). Current definitions give no hints for retryable vs. user-fixable vs. fatal errors.
Tool descriptions are too short (10-35 characters). Current descriptions like 'Read the contents of a file' (28 chars) lack context on WHEN to use, WHAT to expect, and HOW it differs from similar tools. LLMs cannot reliably select the right tool without richer descriptions.
update_plan has an empty input schema (no parameters at all). Unclear what 'planning state' means, how it is updated, what the result is, and why an agent would call it. This tool cannot be reliably invoked without richer documentation.
No tool composition or chaining guidance. If create_directory returns a path, and write_file accepts a path, this should be documented to help agents chain the calls. No output fields documented, so agents cannot know which tool outputs feed into which tool inputs.
No scope or permission declarations visible. Pattern:scope-declaration requires each tool to declare what permissions it needs (e.g., 'read:filesystem', 'write:filesystem', 'execute:shell'). Without this, least-privilege agent configurations are impossible.
morph_edit_file and edit_file perform overlapping functions with no clear distinction. LLMs cannot reliably choose between them without guidance on when to use Morph vs. standard edit.
edit_filemorph_edit_file
Add scope/permission declarations to each tool. Example: 'Requires: read:filesystem. Returns: file content (may contain secrets, redact before returning to user).'
For destructive tools (delete_file, delete_directory, execute_bash), add an explicit warning in the description: 'This operation is IRREVERSIBLE. Consider asking the user for confirmation before proceeding.' Document any available dry-run or preview mechanisms.
For execute_bash, document security constraints explicitly: 'Inputs are validated against a whitelist of safe commands. Commands accessing /etc, /root, or executing sudo are rejected. All user input is shell-escaped.' Or clarify what validation/restriction IS in place.
Document update_plan parameters and output. What is 'planning state'? What fields does the LLM pass and receive? This tool is opaque without richer definition.
Add tool composition hints. Example in write_file description: 'Tip: If the parent directory does not exist, call create_directory first, then write_file. Output returns the absolute path for chaining.'
Implement paginated results for list_directory, search_code, and glob_files if they can return many results. Add limit and offset/cursor parameters, and return a total_count field. Without pagination, large directory listings will blow context windows.
Validate all parameters at tool entry. Return actionable error messages, e.g., 'Invalid command: sudo is not allowed. Requested: sudo apt update. Use apt update without sudo instead.' Help the LLM self-correct in one retry.