Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
Docker MCP server presents 19 tools with complete JSON Schema input definitions and consistent descriptions. Naming is action-verb based and clear (list_containers, create_container, remove_image). Descriptions are adequate (50-150 chars typically), meeting the 10-1024 character baseline. Parameters are typed and include descriptions. However, several quality gaps prevent a higher score: (1) Output schemas are not documented in the visible code, tool definitions show inputs but no explicit return type documentation; (2) Error handling is generic, no evidence of actionable error messages or recovery guidance; (3) No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk categories (READ_ONLY, WRITE, DESTRUCTIVE); (4) Parameter descriptions lack constraint details (e.g., 'ports' object lacks format hints, 'tail' integer lacks min/max bounds); (5) No evidence of dry-run or confirmation patterns for destructive operations; (6) Prompts feature is present but not deeply integrated with tools. The server is functional and usable but lacks polish expected of production-grade agent tools.
Output schemas not documented. Tool definitions show input schemas clearly but no explicit return type documentation visible in the code. LLMs cannot infer what fields to expect from tool responses, limiting their ability to chain tools or extract required IDs.
Missing tool annotations despite clear risk classification. Tools are marked READ_ONLY, WRITE, REVERSIBLE, or DESTRUCTIVE in the metadata, but no readOnlyHint, destructiveHint, or idempotentHint annotations are registered with the tools themselves. This prevents MCP clients from displaying appropriate warnings or limiting agent capabilities.
Document output schemas for every tool. For list_* tools, specify the structure of returned items, include pagination guidance, and document total_count or next_cursor fields. For create_* tools, return the created resource ID and full resource object.
Add tool annotations to the MCP tool registration. Use readOnlyHint=true for list_*, get_*, and fetch_* tools. Use destructiveHint=true for remove_* tools. Use idempotentHint=true for tools like start_container (starting an already-running container is safe to retry).
Enhance parameter descriptions with explicit format and constraint details. For example: 'tail: Number of lines from the end (integer, 1-1000, default 100)'. For 'ports', document the expected structure: 'Mapping of container_port (int or string) to host_port (int or string), e.g. {"8080": "8080", "443": "8443"}'.
Implement structured error responses with actionable recovery guidance. When a container is not found, return 'Container "myapp" not found. Available containers: [list]. Did you mean one of these?' When a command fails, return the exit code, stderr, and a hint like 'Command failed with exit 1. Check image name or entrypoint syntax.'
Add a confirmation pattern for destructive operations. Implement optional --dry-run or --confirm parameters. For high-stakes operations like remove_image or remove_volume, require explicit confirmation in agent code (e.g., return status='pending_confirmation' and require a follow-up call to confirm_deletion).
Clarify parameter semantics in descriptions. For 'environment', specify the dict structure and mention Docker's precedence (env vars can override image defaults). For 'command', clarify whether it's a shell string (entrypoint /bin/sh -c) or exec array (exec directly). Document the difference between 'entrypoint' (replaces ENTRYPOINT) and 'command' (replaces CMD).
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Score history
Overall score trend
↑ 22 points across a rubric change (v1 → v2)
59/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
D
59
<=2025-11-25
v2
2026-03-09
F
37
-
v1
list_volumesread onlysource verified79/100
List Docker volumes
pull_imagewritesource verified81/100
Pull a Docker image from a registry
push_imagewritesource verified81/100
Push a Docker image to a registry
recreate_containerreversiblesource verified77/100
Stop and remove a container, then run a new container. Fails if the container does not exist.
remove_containerdestructivesource verified79/100
Remove a Docker container
remove_imagedestructivesource verified79/100
Remove a Docker image
remove_networkdestructivesource verified79/100
Remove a Docker network
remove_volumedestructivesource verified79/100
Remove a Docker volume
run_containerwritesource verified79/100
Run an image in a new Docker container (preferred over `create_container` + `start_container`)
Parameter constraints incomplete. Numeric parameters lack min/max bounds (e.g., 'tail' integer in fetch_container_logs has no documented range). Object parameters lack format hints (e.g., 'ports' and 'volumes' objects in create_container lack clarity on expected key-value structure). LLMs may pass invalid values requiring validation errors and retries.
No error handling guidance visible. Source code shows tool implementations but no evidence of structured error responses that tell LLMs what to do next (e.g., 'User not found. Try search_users() with a partial name.'). Generic Docker SDK exceptions likely surface without actionable recovery guidance.
Destructive operations lack confirmation pattern. remove_container, remove_image, remove_network, and remove_volume can permanently delete resources. No evidence of dry-run or confirmation step before execution, increasing risk of catastrophic agent errors.
Parameter descriptions lack detail on formats and constraints. Example: 'environment' is described as 'Environment variables dictionary' but does not specify whether the LLM should pass {'KEY': 'value'} or {'KEY=value'} format. 'command' and 'entrypoint' lack clarity on shell vs. exec format.
create_containerrun_containerrecreate_container
Add a discovery tool or resource to list available Docker images by tag and describe their purpose. This helps agents understand what images are available without needing external knowledge. E.g., a resource type 'docker://image-catalog' that returns {"nginx:latest": "web server", "postgres:15": "database"}.
Document output formats and field mappings. Create a resource (e.g., 'docker://api-reference') that LLMs can query to learn the structure of container objects, network objects, and volume objects returned by tools. This enables better downstream reasoning and reduces hallucination.
Implement pagination for list_* tools that return many items. Add 'limit' and 'offset' (or 'limit' and 'cursor') parameters. Document the response structure to include 'total', 'items', and optional 'next_cursor'. Cap default results at 20-50 items.
Add validation and clear error messages in tool implementations. When invalid input is detected (e.g., invalid port mapping, missing required image tag), return a structured error: {"code": "INVALID_PARAMETER", "parameter": "ports", "message": "Port mapping must be string->int or int->int, got...", "examples": [{"8080": 8080}]}.