Agnes AI exposes 4 tools with basic descriptions and input schemas, but lacks critical production-grade patterns. Tool names follow verb_noun convention (write_file, read_file, run_command, run_mcp), which is positive. However, descriptions are minimal (10-50 chars), parameter descriptions are sparse or missing, output schemas are undocumented, and error handling guidance is absent. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite high-risk operations. The run_command and run_mcp tools are IRREVERSIBLE but lack confirmation/dry-run patterns. No pagination, no structured output documentation, no recovery guidance. This is typical of early-stage agent tooling, functional but not production-ready.

• Add tool annotations: mark write_file and run_command with destructiveHint=true, read_file with readOnlyHint=true, run_mcp with destructiveHint=true (context-dependent). This signals risk to LLMs.
• Document output schemas for all tools. E.g., read_file returns {content: string, size_bytes: number, encoding: string}; run_command returns {exit_code: number, stdout: string, stderr: string, duration_ms: number}.
• Expand parameter descriptions with format, constraints, and examples. E.g., 'command: shell command string (bash/sh syntax); max 10000 chars; timeout 30s; runs in workspace root; returns exit code + stdout/stderr'.
• Add error recovery guidance. E.g., 'If run_command fails with exit_code != 0, check stderr for details. Common causes: missing tool (install via npm/cargo), permission denied (check file mode), timeout (command too slow).'
• Implement confirmation pattern for destructive ops: add a dry_run parameter to write_file and run_command, or introduce a separate confirm_operation tool that LLMs must call before executing irreversible actions.

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry