Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
PikoChan exposes 13 tools via HTTP. Most tool definitions are visible in the source code with basic descriptions and parameter lists, but critically lack rigorous input schemas, parameter type validation, and output documentation. Tool naming is reasonable (verb-starting: mcpToolCall, shell, openURL, mcpInstall, health, chat, history, logs, memories, config, mood, mcp, cron), but several combine multiple responsibilities or lack clarity. Descriptions are present but often generic (e.g., 'Execute arbitrary shell commands with confirmation handling' for shell). Parameter descriptions exist but are minimal, many lack format/constraint specifications. No visible output schema documentation for any tool. Error handling appears basic (relies on connection-level HTTP error codes rather than structured recovery guidance). The server implements a custom HTTP framework rather than using a standard MCP library, which increases the risk of missing patterns and making tool composition harder.
Tools (13)
chatread only50/100
Send a chat message to the brain for processing
configread only50/100
Get current configuration
cronwritesource verified55/100
List, add, update, pause, and manage cron jobs
healthread only50/100
Check HTTP server and voice server health status
historyread only50/100
Retrieve chat history with optional filtering
logsread only50/100
Retrieve system logs with filtering
mcpread only50/100
List available MCP servers and their tools
mcpInstallwrite50/100
Install or configure an MCP server by name
mcpToolCallwrite50/100
Execute a tool from an MCP server by server name and tool name
Missing output schemas for all tools. LLMs cannot infer response structure, forcing them to guess field names and downstream tool compatibility. No documented return types means tool chaining is error-prone.
Parameter constraints are undocumented. Enum values are missing (e.g., 'level' in logs, 'mood' in mood, 'action' in cron), format rules are absent (e.g., URL validation, command length limits, schedule syntax), and type validation is weak. LLMs will hallucinate invalid values.
logsmoodcronshellopenURLchathistorymemories
HIGH
Recommendations
Document output schema for every tool. Use JSON Schema format: {'type': 'object', 'properties': {...}, 'required': [...]}. For discovery tools, include nested structures. Example for 'mcp': {'type': 'object', 'properties': {'servers': {'type': 'array', 'items': {'type': 'object', 'properties': {'name': {'type': 'string'}, 'tools': {'type': 'array', 'items': {'type': 'object', 'properties': {'name', 'description', 'inputSchema'}}}}}}}
Convert all free-form string parameters to enums where values are known. Example: 'level' in logs should be {'type': 'string', 'enum': ['info', 'warning', 'error']}. 'action' in cron should be {'type': 'string', 'enum': ['list', 'add', 'update', 'pause', 'resume', 'delete']}. 'mood' should declare valid moods as an enum.
Split 'cron' tool into six separate tools: list_cron_jobs (parameters: none; returns array of jobs), create_cron_job (parameters: schedule, command; returns job_id), update_cron_job (parameters: id, schedule, command), pause_cron_job (parameters: id), resume_cron_job (parameters: id), delete_cron_job (parameters: id). This follows single-responsibility principle and makes LLM reasoning simpler.
Expand parameter descriptions to 50 - 150 characters and include format/constraint detail. Current: 'Log level filter (info, warning, error)' → Improved: 'Filter logs by severity. Valid values: info (informational messages), warning (potential issues), error (failures). Omit to return all levels.'
Add error handling and recovery guidance. For 'shell': 'If command fails, response.error contains the exit code and stderr. Suggest alternative commands or ask the user to refine the shell syntax. Shell type is /bin/bash.' For 'mcpInstall': 'If server not found, call mcp tool first to list available servers. If install fails, check server config file format.'
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Score history
Overall score trend
First recorded score · v2 rubric
46/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
F
46
<=2025-11-25
v2
memoriesread only50/100
Retrieve stored memories from the brain
moodwrite50/100
Set the current mood of the assistant
openURLread only50/100
Open a URL in the default browser
shelldestructive50/100
Execute arbitrary shell commands with confirmation handling
'cron' tool combines five actions (list, add, update, pause, resume, delete) into a single tool. This violates single-responsibility principle and forces complex conditional logic in the LLM. Should split into separate tools: list_cron_jobs, create_cron_job, update_cron_job, pause_cron_job, resume_cron_job, delete_cron_job.
'shell' tool accepts arbitrary commands without documented restrictions. No guidance on safe defaults, dangerous command detection, or sandboxing. Combined with DESTRUCTIVE risk classification, this requires explicit confirmation flow documentation and error recovery guidance.
'mcpInstall' and 'mcpToolCall' combine concerns and lack idempotency documentation. 'mcpInstall' conflates install and configure. 'mcpToolCall' requires the LLM to know server names without discovery support. Both need clear error guidance and chaining IDs in responses.
Parameter descriptions are consistently too short (most under 40 chars) and lack actionable detail. E.g., 'Log level filter (info, warning, error)' should be an enum with valid values documented. 'Subsystem to filter by' should list available subsystems or explain discovery.
Discovery tools (health, config, mcp, history) lack guidance on when to call them or what structure they expose. For example, 'mcp' should explain: 'Call this first to discover available MCP servers and their tools. Response structure: {servers: [{name, tools: [{name, description, inputSchema}]}]}', this guides tool chaining.
No documented error handling or recovery guidance. Tools return HTTP status codes (visible from connection handling) but no structure for LLM-actionable errors. E.g., if 'shell' command fails, what does the response contain? Can the LLM retry? Should it suggest alternatives?
Document pagination for list tools. 'get_chat_history' and 'get_logs' should accept 'offset' and 'limit' parameters (e.g., limit 1 - 1000, default 20) and return 'total_count' and 'next_offset' so agents can paginate large result sets.
Add idempotency and confirmation guidance. For 'shell' (DESTRUCTIVE): 'This tool executes arbitrary commands. High-risk operations (rm, shutdown, etc.) require explicit confirmation from the user. Return a confirmation request before executing destructive commands.' For 'mcpInstall': 'This tool modifies server configuration. Idempotent: calling with the same serverName is safe and will return current config without side effects.'
Include chaining references in output schemas. If 'get_chat_history' returns messages, include 'message_id' so agents can pipe results to 'create_reply_to_message'. If 'list_mcp_servers' returns servers, include 'server_name' so agents can call 'call_mcp_tool' or 'install_mcp_server'.
Add examples to descriptions (not in parameter fields, but in the tool description) to guide LLM usage. Example for 'set_mood': 'Set the assistant's mood to affect response tone. Example usage: set_mood(mood="cheerful") makes subsequent chat responses upbeat. Current mood affects all downstream responses until changed.'
Clarify discovery and prerequisites. For 'call_mcp_tool': 'Call list_mcp_servers first to discover available servers and tools. Then call this tool with the exact server name and tool name from the discovery response.' For 'create_cron_job': 'Schedule format is standard cron syntax (5 fields: minute, hour, day-of-month, month, day-of-week). Example: "0 9 * * 1" runs at 9 AM every Monday.'
Validate and document secret handling. Review whether API keys, tokens, or credentials are ever passed as parameters. If so, migrate to server-side secret injection via environment variables or secure vaults. Document in tool descriptions: 'This tool uses credentials from environment variables MYPROVIDER_API_KEY and MYPROVIDER_API_SECRET. Do not pass credentials as parameters.'