improve: enhance tool descriptions for better LLM agent tool selection

src/mcp_server_docker/server.py

@@ -243,97 +243,97 @@ async def list_tools() -> list[types.Tool]:
     return [
         types.Tool(
             name="list_containers",
-            description="List all Docker containers",
+            description="List all Docker containers on the system, including running and stopped containers. Use when the user wants to view, inspect, or get an overview of existing containers and their current states. Do not use when you need to see available Docker images (use list_images instead) or when you want to create a new container (use create_container instead). Accepts optional filtering parameters such as `status` (e.g., "running", "exited") and `name` for specific container matching. e.g., filtering by status="running" to show only active containers. Raises an error if Docker daemon is not running or accessible.",
             inputSchema=ListContainersInput.model_json_schema(),
         ),
         types.Tool(
             name="create_container",
-            description="Create a new Docker container",
+            description="Create a new Docker container from an existing image without starting it. Use when the user wants to prepare a container with specific configuration before manually starting it later. Do not use when you need to create and immediately run a container (use run_container instead). Accepts `image` (required), `name` (optional container name), `ports` (optional port mappings), and `environment` (optional env vars). e.g., image="nginx:latest", name="my-web-server". Raises an error if the specified image does not exist locally.",
             inputSchema=CreateContainerInput.model_json_schema(),
         ),
         types.Tool(
             name="run_container",
-            description="Run an image in a new Docker container (preferred over `create_container` + `start_container`)",
+            description="Run a Docker image in a new container with a single command. Use when the user wants to quickly start a containerized application or service from an existing image. Do not use when you need fine-grained control over container creation and startup (use create_container then start_container instead). Accepts `image` (required), `name` (optional container name), `ports` (optional port mappings), and `environment` (optional env vars). e.g., image="nginx:latest", ports=["80:8080"], name="my-web-server". Raises an error if the specified image does not exist locally or cannot be pulled.",
             inputSchema=CreateContainerInput.model_json_schema(),
         ),
         types.Tool(
             name="recreate_container",
-            description="Stop and remove a container, then run a new container. Fails if the container does not exist.",
+            description="Recreate a Docker container by stopping, removing, and running a fresh instance with the same configuration. Use when the user wants to reset a container's state, apply configuration changes, or resolve issues that require a clean restart. Do not use when you only need to restart an existing container (use stop_container then start_container instead) or create a brand new container (use run_container instead). Accepts `container_name` or `container_id` (required), e.g., "web-server" or "nginx-prod". Fails if the specified container does not exist or cannot be stopped.",
             inputSchema=RecreateContainerInput.model_json_schema(),
         ),
         types.Tool(
             name="start_container",
-            description="Start a Docker container",
+            description="Start a Docker container that already exists but is currently stopped. Use when the user wants to resume or restart a previously created container that has been stopped. Do not use when you need to create and run a new container from an image (use run_container instead) or when the container doesn't exist yet (use create_container first). Accepts `container_id` or `container_name` (required), e.g., "my-web-app" or "3f2c1a8b9e4d". Raises an error if the container is already running or does not exist.",
             inputSchema=ContainerActionInput.model_json_schema(),
         ),
         types.Tool(
             name="fetch_container_logs",
-            description="Fetch logs for a Docker container",
+            description="Fetch logs from a running or stopped Docker container for debugging and monitoring purposes. Use when the user wants to view container output, debug application issues, or monitor container behavior. Do not use when you need to see which containers are available (use list_containers instead). Accepts `container_id` or `container_name` (required), `lines` (optional number of recent lines), and `follow` (optional boolean for streaming). e.g., container_name="web-server", lines=100. Raises an error if the container does not exist or has been removed.",
             inputSchema=FetchContainerLogsInput.model_json_schema(),
         ),
         types.Tool(
             name="stop_container",
-            description="Stop a Docker container",
+            description="Stop a running Docker container by gracefully shutting it down. Use when the user wants to halt a currently running container without removing it from the system. Do not use when you need to permanently delete the container (use remove_container instead) or when you want to stop and immediately restart it (use recreate_container instead). Accepts `container_id` or `container_name` (required), e.g., "my-web-app" or "a1b2c3d4e5f6". Raises an error if the container is already stopped or does not exist.",
             inputSchema=ContainerActionInput.model_json_schema(),
         ),
         types.Tool(
             name="remove_container",
-            description="Remove a Docker container",
+            description="Remove a Docker container from the system. Use when the user wants to permanently delete a stopped container to free up disk space or clean up unused containers. Do not use when the container is still running (use stop_container first) or when you need to recreate it immediately (use recreate_container instead). Accepts `container_id` or `container_name` (required), e.g., "my-app-container" or "a1b2c3d4e5f6". Raises an error if the container is currently running or does not exist.",
             inputSchema=RemoveContainerInput.model_json_schema(),
         ),
         types.Tool(
             name="list_images",
-            description="List Docker images",
+            description="List all Docker images available on the local system. Use when the user wants to view, inspect, or inventory available Docker images before running containers or managing storage. Do not use when you need to download a new image (use pull_image instead) or create an image (use build_image instead). Accepts optional filtering parameters such as `repository` and `tag`. e.g., filtering by "nginx" repository or "latest" tag. Fails if Docker daemon is not running or accessible.",
             inputSchema=ListImagesInput.model_json_schema(),
         ),
         types.Tool(
             name="pull_image",
-            description="Pull a Docker image",
+            description="Pull a Docker image from a registry to the local Docker daemon. Use when the user wants to download or update an image before creating containers from it. Do not use when you need to create and run a container immediately (use run_container instead). Accepts `image` (required, string with optional tag), e.g., "nginx:latest" or "ubuntu:20.04". Raises an error if the image does not exist in the registry or network connectivity fails.",
             inputSchema=PullPushImageInput.model_json_schema(),
         ),
         types.Tool(
             name="push_image",
-            description="Push a Docker image",
+            description="Push a Docker image to a registry or repository. Use when the user wants to upload a locally built or tagged image to Docker Hub, a private registry, or another remote repository for sharing or deployment. Do not use when you need to download an image from a registry (use pull_image instead). Accepts `image` (required, image name with optional tag), `registry` (optional, defaults to Docker Hub), and `tag` (optional, defaults to "latest"). e.g., image="myapp:v1.0" or "registry.example.com/myapp". Raises an error if the image does not exist locally or authentication credentials are invalid.",
             inputSchema=PullPushImageInput.model_json_schema(),
         ),
         types.Tool(
             name="build_image",
-            description="Build a Docker image from a Dockerfile",
+            description="Build a Docker image from a Dockerfile in the current directory or specified path. Use when the user wants to create a custom Docker image from source code, configuration files, or application dependencies. Do not use when you need to download an existing image from a registry (use pull_image instead). Accepts `dockerfile_path` (optional, defaults to "./Dockerfile"), `image_name` (required), and `build_context` (optional, defaults to current directory). e.g., image_name="myapp:latest", dockerfile_path="./docker/Dockerfile". Raises an error if the Dockerfile contains invalid syntax or required base images are unavailable.",
             inputSchema=BuildImageInput.model_json_schema(),
         ),
         types.Tool(
             name="remove_image",
-            description="Remove a Docker image",
+            description="Remove a Docker image from the local system. Use when the user wants to delete unused images to free up disk space or clean up after development work. Do not use when you need to download an image from a registry (use pull_image instead). Accepts `image` (required: image name or ID), and `force` (optional: boolean to force removal). e.g., image="nginx:latest" or image="sha256:abc123". Raises an error if the image is currently being used by a running container.",
             inputSchema=RemoveImageInput.model_json_schema(),
         ),
         types.Tool(
             name="list_networks",
-            description="List Docker networks",
+            description="List all Docker networks available on the system. Use when the user wants to inspect, review, or troubleshoot network configurations and connectivity between containers. Do not use when you need to create a new network (use create_network instead) or remove an existing network (use remove_network instead). Accepts optional filtering parameters such as `name` and `driver` type. e.g., filtering by bridge networks or custom network names like "my-app-network". Fails if Docker daemon is not running or accessible.",
             inputSchema=ListNetworksInput.model_json_schema(),
         ),
         types.Tool(
             name="create_network",
-            description="Create a Docker network",
+            description="Create a Docker network to enable communication between containers. Use when the user wants to establish isolated networking for multi-container applications or microservices. Do not use when you need to view existing networks (use list_networks instead) or remove a network (use remove_network instead). Accepts `name` (required), `driver` (optional: "bridge", "host", "overlay"), and `options` (optional key-value pairs). e.g., name="my-app-network", driver="bridge". Raises an error if a network with the same name already exists.",
             inputSchema=CreateNetworkInput.model_json_schema(),
         ),
         types.Tool(
             name="remove_network",
-            description="Remove a Docker network",
+            description="Remove a Docker network from the system. Use when the user wants to clean up unused networks or delete a specific network that is no longer needed. Do not use when you need to see available networks first (use list_networks instead). Accepts `network_name` or `network_id` (required), e.g., "my-custom-network" or "bridge". Raises an error if the network is still in use by running containers or does not exist.",
             inputSchema=RemoveNetworkInput.model_json_schema(),
         ),
         types.Tool(
             name="list_volumes",
-            description="List Docker volumes",
+            description="List all Docker volumes on the system. Use when the user wants to inspect, review, or manage persistent data storage volumes. Do not use when you need to create a new volume (use create_volume instead). Accepts optional filter parameters such as `dangling` (boolean) and `driver` (string). e.g., dangling=true to show unused volumes or driver="local" for local volumes. Raises an error if the Docker daemon is not running or accessible.",
             inputSchema=ListVolumesInput.model_json_schema(),
         ),
         types.Tool(
             name="create_volume",
-            description="Create a Docker volume",
+            description="Create a Docker volume for persistent data storage that survives container restarts and removals. Use when the user wants to store application data, database files, or configuration that must persist across container lifecycles. Accepts `name` (required string for volume identifier) and `driver` (optional, defaults to "local"). e.g., name="postgres_data" or name="app_logs". Do not use when you need to mount host directories directly into containers (use create_container with bind mounts instead). Raises an error if a volume with the same name already exists.",
             inputSchema=CreateVolumeInput.model_json_schema(),
         ),
         types.Tool(
             name="remove_volume",
-            description="Remove a Docker volume",
+            description="Remove a Docker volume from the system permanently. Use when the user wants to delete an unused volume to free up disk space or clean up after container removal. Accepts `volume_name` (required string), e.g., "my-data-volume" or "postgres_data". Do not use when you need to create or list volumes (use create_volume or list_volumes instead). Raises an error if the volume is currently in use by a running container or if the volume does not exist.",
             inputSchema=RemoveVolumeInput.model_json_schema(),
         ),
     ]