podman-ai has severe definition quality issues. While 6 tools are present with names and basic descriptions, the implementation lacks proper MCP tool registration, parameter schemas are missing for most tools, and descriptions are generic. Tools are not registered through proper MCP mechanisms, they exist as Python functions but lack formal schema documentation. The codebase shows a custom wrapper around Ollama and Podman but does not implement the MCP tool definition protocol correctly. No JSON Schema validation present. Parameter descriptions are minimal or absent. Output schemas are completely undocumented.
Tools (6)
build_promptread onlysource verified33/100
Builds a context-rich prompt for Ollama with example, instructions, and optional podman help text.
No MCP tool registration visible. Tools are defined as Python functions but not registered with MCP protocol. The server appears to be a CLI tool wrapper, not a proper MCP server with tools exposed via the MCP protocol.
No input parameter schemas visible. The server defines parameters (user_query, help_context, command) but lacks JSON Schema definitions with type, description, required, and constraints. Parameter schemas are essential for LLM tool use.
Output schemas are completely undocumented. No return type specifications, field names, or structure definitions visible. LLMs cannot infer what data structure to expect from tool responses.
query_ollama
Recommendations
Implement proper MCP server protocol. The codebase must expose tools through an MCP-compliant server (stdio, HTTP, or SSE transport) with correct tool registration, not as a standalone CLI tool.
Define complete JSON Schema for all tool inputs. Each tool parameter must have type (string, number, boolean, etc.), description (50-150 chars), and constraints (enum, pattern, min/max). Example: {'type': 'string', 'description': 'The Podman command to execute (must start with podman or podman-remote)', 'pattern': '^podman(-remote)?\s+\S+.*$'}
Document all output schemas. For each tool, specify the return type (object, array, string, etc.), all field names, field types, and field descriptions. Example for execute_podman_command: {'type': 'object', 'properties': {'exit_code': {'type': 'integer', 'description': 'Shell exit code'}, 'stdout': {'type': 'string', 'description': 'Command output'}, 'stderr': {'type': 'string', 'description': 'Error output if any'}}}
Expand tool descriptions to 100-150 characters. Current descriptions like 'Get the output of podman help' are too terse. Rewrite as: 'Retrieve Podman CLI help text for reference in prompt building. Returns the full output of podman help command. Used to enrich LLM context about available Podman subcommands.'
Add parameter descriptions to all inputs. Every parameter must have a description explaining what it controls, valid values, and format. Example: 'user_query (string, required): A plain-language instruction to convert to a Podman command. Example: "list all running containers". The LLM will infer the appropriate podman subcommand.'
Tool descriptions are too brief and lack context. 'Get the output of podman help' (30 chars) does not explain when to use it vs build_prompt, what format the output is in, or what the LLM should do next.
Parameter descriptions missing or minimal. 'user_query' has description but many parameters lack descriptions entirely. LLMs cannot disambiguate parameter intent.
execute_podman_command accepts arbitrary command strings with no validation or constraints. The 'command' parameter should have a pattern, enum constraints, or validation logic documented. This enables injection attacks.
No error handling guidance. Tool descriptions do not explain what errors are possible, when to retry, or how to recover. The RISKY_COMMANDS config exists but is not reflected in tool documentation.
confirm_execution_if_needed requires user interaction, but no confirmation protocol is documented. This suggests a stateful interaction model that is not compatible with stateless MCP.
Tool composition is poor. build_prompt and query_ollama likely work together, but this dependency is not documented. Similarly, is_valid_podman_command and execute_podman_command should be chained, but the tool interface does not enforce this.
Risky command detection and confirmation logic is buried in Python code (confirm_execution_if_needed). The list of risky commands comes from YAML config but is not exposed to the LLM. The LLM cannot see which commands trigger confirmation without calling the tool.
confirm_execution_if_neededexecute_podman_command
Implement input validation with clear error messages. Instead of silently accepting arbitrary commands, validate against a whitelist or regex. Return structured errors: {'error': 'Invalid command', 'reason': 'command must start with "podman"', 'valid_subcommands': ['run', 'ps', 'exec', ...]}
Document tool dependencies and composition order. Create a tool use guide explaining: (1) Call run_podman_help to get available commands, (2) Call build_prompt with the help text, (3) Call query_ollama to generate a command, (4) Call is_valid_podman_command to validate, (5) Call confirm_execution_if_needed for risky commands, (6) Call execute_podman_command to run.
Replace stateful confirmation with a dry-run pattern. Instead of confirm_execution_if_needed (which requires user interaction), add a dry_run parameter to execute_podman_command. Allow the LLM to first run in dry-run mode to preview the result, then call again with dry_run=false.
Add tool annotations. Mark execute_podman_command and confirm_execution_if_needed as destructiveHint=true to signal to the LLM that these are high-risk operations. Mark query_ollama and run_podman_help as readOnlyHint=true.
Reduce required parameters. Consider making podman_help_text optional with a smart default in build_prompt. If not provided, the tool should call run_podman_help internally rather than forcing the LLM to chain calls.
Expose risky command list. Create a get_risky_commands() tool or document risky commands in execute_podman_command and confirm_execution_if_needed descriptions so the LLM knows which commands trigger confirmation.
Add pagination and limit guidance if results can be large. For run_podman_help, cap output to 2000 chars (already done in code) but document this in the tool description so the LLM knows the help text may be truncated.
Implement idempotency where possible. Clarify which tools are idempotent (query_ollama, is_valid_podman_command, run_podman_help) vs stateful (execute_podman_command). Agents rely on this to decide whether to retry.