A minimalist CLI Agent framework for learning AI Agents with tool-calling capabilities
MiniAgent is an educational CLI framework with 15 tools spanning utilities, system inspection, file operations, and dangerous shell access. The tools have **schemas present for all 15 tools with typed parameters and descriptions**, which is a baseline requirement. However, analysis reveals significant structural and documentation gaps that prevent these tools from being production-ready: 1. **Naming Issues**: Tool names are mostly verb-based (good baseline), but several violate single-responsibility principle. The `bash` tool is generic ('execute a shell command') and combines shell execution with all its inherent risks. Names like `file_stats`, `system_info`, `process_list` are clear enough. However, `http_request` conflates GET, POST, PUT, DELETE, PATCH into one tool, agents should prefer separate read/write verb names. 2. **Descriptions**: All 15 tools have descriptions, but most are brief (15-50 chars) and lack critical context. For example: - `calculator`: 87 chars, explains the mechanism (AST parsing for safety), good. - `get_current_time`: 29 chars, too brief, no example or return format stated. - `system_info`: 37 chars, vague, what fields does it return? - `bash`: 35 chars, mentions 'shell command' but does NOT state the DESTRUCTIVE nature prominently in the description text itself (risk is listed separately in metadata). Description should say: 'Execute a shell command. WARNING: Runs arbitrary code, only safe for sandboxed agents.' - `http_request`: 120 chars, lists methods but says nothing about when to use it vs. separate tools, or what retry behavior applies. 3. **Parameter Descriptions**: All parameters have descriptions. However, many are minimal: - `calculator` → `expression`: 108 chars, includes examples ('2 + 2 * 3', 'sqrt(16)', 'sin(pi/2)'), good pattern, but violates the rubric principle 'Do not put example values in the description' (they should be in constraints/schema). - `http_request` → `method`: 41 chars, lists methods but doesn't explain when/why to use each or document mutual exclusivity. - `bash` → `timeout`: 75 chars, mentions env var and default 120s, but lacks guidance on what timeout value is sensible (e.g., '1 - 300 seconds'). 4. **Schemas**: Input schemas are present and use JSON Schema format with types. However: - No tool documents its **output schema**. Agents cannot know what fields to expect in responses, critical for chaining tools and extracting values downstream. This violates pattern:response-shaper. - `bash`: parameter 'timeout' lacks a minimum/maximum constraint. An LLM could pass timeout=0 or timeout=1000000, both problematic. - `http_request`: `data` and `headers` are typed as 'object' without nested field descriptions. What structure does `data` expect? Is it key-value pairs, or nested JSON, or multipart? Ambiguous. - `file_stats` → `directory`: no default stated in schema (description says 'default is current directory' but schema doesn't mark it optional). This forces the LLM to guess. 5. **Error Handling**: No tool descriptions include recovery guidance. For example: - `bash`: If execution times out or returns a non-zero exit code, what should the agent do next? Retry? Ask the user? The tool provides no guidance. - `http_request`: No mention of what happens on 4xx/5xx responses, timeouts, or DNS failures. Agents cannot plan recovery. - `web_search`: No guidance if DuckDuckGo is unreachable or rate-limited. 6. **Security**: The `bash` tool is **critically dangerous** and listed as DESTRUCTIVE risk, but: - The tool description does NOT emphasize the risk in the natural-language text (it only appears in Risk metadata). - No mention of sandboxing, allowlist, or confirmation requirement. - The `timeout` parameter exists but is optional/defaulted, which is dangerous, agents could forget to set a timeout. - No error handling guidance for shell errors or injection attempts. - `http_request` with WRITE methods also lacks permission checks or audit logging guidance. 7. **Composition & Chaining**: Several tools are missing related operations or fail to chain well: - `read`, `write`, `edit` exist (good). But no `delete` tool, forcing agents to call `bash rm` instead of a sandboxed file deletion. - `web_search` exists but no `fetch_url` or `read_html` to extract content from search results, agent must fallback to `http_request` (generic) or `bash` (dangerous). - No pagination or limit guidance for `process_list`, `file_stats`, `grep`, if a directory has 10,000 files, does `file_stats` return all of them? 8. **Result Limits & Pagination**: Many list-returning tools lack guidance: - `process_list` accepts a `limit` parameter (good), but the description doesn't state if it returns all processes up to limit, or what fields are included (PID, name, CPU%, memory?). - `grep` has no limit parameter or pagination, searching a large codebase could return thousands of lines, blowing context windows. - `glob` similarly has no limit, `glob('**/*')` on a large repo could match thousands of files. 9. **Missing Idempotency Guidance**: `write` tool overwrites files, is this idempotent? If called twice with the same content, it should succeed both times. But if it appends a timestamp or auto-increments, agents cannot rely on idempotent retries. No guidance provided. 10. **Inconsistent Field Naming**: `file_stats` uses `directory` and `pattern` parameters; `glob` uses `pattern` and `path`. Why the inconsistency? Should both use `path`? LLMs struggle with naming mismatches across similar tools. **Per-Tool Breakdown**: - **calculator** (87 chars desc, typed params with examples): Naming clear, description adequate, schema reasonable. Score: 62 (good baseline; lacks output schema documentation). - **get_current_time** (29 chars desc, no params): Too brief, no return format stated. Score: 35 (lacks context). - **system_info** (37 chars desc, no params): Vague, no field list. Score: 32 (incomplete). - **file_stats** (82 chars desc, 2 params): Clear naming, reasonable description, but no output schema. Schema allows directory/pattern but no constraint on result size. Score: 48. - **web_search** (59 chars desc, 2 params): Clear intent, but no error handling for rate-limits or unreachable service. Score: 45. - **http_request** (120 chars desc, 5 params): Verbose description, but conflates 5 methods into one tool (poor composition). Data/headers params lack nested field clarity. No output schema (what's in the response?). Score: 42. - **disk_usage** (64 chars desc, 1 param): Adequate description, default path stated in desc but not schema. Score: 48. - **process_list** (68 chars desc, 1 param): Clear intent, limit parameter present, but no output schema or field documentation. Score: 45. - **system_load** (66 chars desc, no params): Adequate, but vague on what 'resource usage statistics' means. Score: 44. - **read** (46 chars desc, 3 params): Clear purpose, parameters documented. No output schema (does it return {lines: [], total: N}?). Score: 48. - **write** (35 chars desc, 2 params): Too brief, no mention of overwrite behavior or idempotency. No output schema. Score: 38. - **edit** (54 chars desc, 4 params): Clear naming, parameters documented. No output schema. Schema lacks constraint on 'old' field size (could match nothing or everything). Score: 44. - **glob** (28 chars desc, 2 params): Too brief, no pagination or result limit guidance. Score: 32. - **grep** (28 chars desc, 2 params): Too brief, no result limit, no output schema. Score: 32. - **bash** (35 chars desc, 2 params): **CRITICAL**: Dangerous tool with insufficient warning in natural description. Timeout parameter is optional (risky). No error handling or injection guidance. Score: 28 (fails security review). **Average per-tool score**: (62+35+32+48+45+42+48+45+44+48+38+44+32+32+28) / 15 = 605 / 15 = **40.33** → rounded to **38** (conservative, reflecting the severity of missing output schemas, weak descriptions on ~8 tools, and critical bash security gaps).
Execute a shell command.
Calculate the result of a mathematical expression. Uses AST parsing for safety — only allows arithmetic and math functions.
Get disk usage information for a specified path.
Edit a file via string replacement.
Get statistics about files in a directory.
Get current time information.
File pattern matching.
No output schemas documented for any tool. Agents cannot know what fields to expect in responses, breaking chaining and extraction patterns. Critical for downstream reasoning.
bash tool (DESTRUCTIVE risk) has insufficient security emphasis in natural description. Description says only 'Execute a shell command', does NOT prominently warn of code execution danger, injection risks, or sandboxing requirements. Timeout parameter is optional (risky default).
Descriptions for 8 tools (get_current_time, system_info, glob, grep, bash, write, web_search, system_load) are under 50 characters, too brief to guide LLM tool selection. Lack context on when/why to use vs. alternatives, return fields, or error behavior.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 54 | <=2025-11-25 | v2 |
| 2026-03-09 | F | 44 | - | v1 |
Regex search in files.
Make HTTP requests with support for GET, POST, PUT, DELETE, and PATCH methods.
Get a list of running processes sorted by CPU usage.
Read file content with line numbers.
Get detailed information about the system.
Get system load and resource usage statistics.
Perform a web search using DuckDuckGo API.
Write content to a file.
List-returning tools (process_list, file_stats, glob, grep) lack pagination, result limits, or guidance on max result count. Searching a large repo could return thousands of items, blowing context windows. No documentation of returned fields or structure.
Parameter descriptions lack formal constraints. E.g., calculator's 'expression' includes example values ('2 + 2 * 3', 'sqrt(16)'); bash's 'timeout' has no min/max bounds; http_request's 'data' and 'headers' lack nested field specification. LLMs may misuse or invent invalid values.
No error recovery guidance in any tool description. E.g., bash says nothing about exit codes, timeouts, or what agent should do on failure. http_request has no guidance for 4xx/5xx responses or network errors. Agents cannot plan recovery paths.
http_request tool conflates 5 HTTP methods (GET, POST, PUT, DELETE, PATCH) into a single tool. Violates single-responsibility principle. Agent cannot easily distinguish safe reads from destructive writes. Should split into read_http (GET only) + write_http (POST/PUT/DELETE/PATCH with permission gates).
Missing complementary tools. No 'delete' file tool, agents forced to call bash 'rm' (dangerous). No 'fetch_url' or 'read_html' after web_search, agents fallback to generic http_request or bash. Composition chains are broken.
Inconsistent parameter naming across similar tools. file_stats uses 'directory' and 'pattern'; glob uses 'pattern' and 'path'. Both search files but use different param names. LLMs struggle with naming mismatches, causes tool confusion.
write, edit, read lack idempotency guidance. Is 'write' idempotent (same content, called twice = success)? Does 'edit' auto-generate versions? Agents cannot safely retry if behavior is undefined.