chore: improve tools description (#29)

Signed-off-by: Tomasz Janiszewski <tomek@redhat.com>
Co-authored-by: Mladen Todorovic <mtodor@gmail.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: 3 people

internal/toolsets/config/tools.go

@@ -68,8 +68,10 @@ func (t *listClustersTool) GetName() string {
 // GetTool returns the MCP Tool definition.
 func (t *listClustersTool) GetTool() *mcp.Tool {
 	return &mcp.Tool{
-		Name:        t.name,
-		Description: "List all clusters managed by StackRox with their IDs, names, and types",
+		Name: t.name,
+		Description: "List all clusters managed by StackRox with their IDs, names, and types." +
+			" Use this tool to get cluster information," +
+			" or when you need to map a cluster name to its cluster ID for use in other tools.",
 		InputSchema: listClustersInputSchema(),
 	}
 }
@@ -84,11 +86,13 @@ func listClustersInputSchema() *jsonschema.Schema {
 
 	schema.Properties["offset"].Minimum = jsonschema.Ptr(0.0)
 	schema.Properties["offset"].Default = toolsets.MustJSONMarshal(defaultOffset)
-	schema.Properties["offset"].Description = "Starting index for pagination (0-based)"
+	schema.Properties["offset"].Description = "Starting index for pagination (0-based)." +
+		" When using pagination, always provide both offset and limit together. Default: 0."
 
 	schema.Properties["limit"].Minimum = jsonschema.Ptr(0.0)
 	schema.Properties["limit"].Default = toolsets.MustJSONMarshal(defaultLimit)
-	schema.Properties["limit"].Description = "Maximum number of clusters to return (default: 0 - unlimited)"
+	schema.Properties["limit"].Description = "Maximum number of clusters to return." +
+		" When using pagination, always provide both limit and offset together. Use 0 for unlimited (default)."
 
 	return schema
 }

internal/toolsets/vulnerability/clusters.go

@@ -71,9 +71,14 @@ func (t *getClustersForCVETool) GetTool() *mcp.Tool {
 		Name: t.name,
 		Description: "Get list of clusters where a specified CVE is detected in Kubernetes orchestrator components" +
 			" (kube-apiserver, kubelet, etcd, etc.)." +
-			" Returns clusters where the Kubernetes infrastructure itself has the vulnerability." +
-			" For comprehensive CVE analysis, also check get_deployments_for_cve (application workloads)" +
-			" and get_nodes_for_cve (node OS packages).",
+			" USAGE PATTERNS:" +
+			" 1) When user asks 'Is CVE-X detected in my clusters?' (plural, general question):" +
+			" Call ALL THREE CVE tools (get_clusters_with_orchestrator_cve, get_deployments_for_cve, get_nodes_for_cve)" +
+			" for comprehensive coverage." +
+			" 2) When user asks specifically about 'orchestrator', 'Kubernetes components'," +
+			" or 'control plane': Use ONLY this tool." +
+			" 3) For single cluster queries (e.g., 'in cluster X'): First call list_clusters to get cluster ID," +
+			" then call ONLY this tool with filterClusterId.",
 		InputSchema: getClustersForCVEInputSchema(),
 	}
 }
@@ -91,8 +96,12 @@ func getClustersForCVEInputSchema() *jsonschema.Schema {
 	schema.Required = []string{"cveName"}
 
 	schema.Properties["cveName"].Description = "CVE name to filter clusters (e.g., CVE-2021-44228)"
-	schema.Properties["filterClusterId"].Description = "Optional cluster ID to verify if a specified CVE" +
-		" is detected on that cluster"
+	schema.Properties["filterClusterId"].Description =
+		"Optional cluster ID to verify if CVE is detected in a specific cluster." +
+			" Only use this parameter when the user's query explicitly mentions a specific cluster name." +
+			" When checking if a CVE exists at all, call without this parameter to check all clusters at once." +
+			" To resolve cluster names to IDs, use list_clusters tool first." +
+			" If the cluster doesn't exist, respond that the CVE is not detected in that cluster (since it doesn't exist)."
 
 	return schema
 }

internal/toolsets/vulnerability/clusters_test.go

@@ -35,7 +35,8 @@ func TestGetClustersForCVETool_GetTool(t *testing.T) {
 
 	require.NotNil(t, mcpTool)
 	assert.Equal(t, "get_clusters_with_orchestrator_cve", mcpTool.Name)
-	assert.Contains(t, mcpTool.Description, "clusters where a specified CVE is detected")
+	assert.Contains(t, mcpTool.Description, "clusters where")
+	assert.Contains(t, mcpTool.Description, "CVE is detected")
 	assert.NotNil(t, mcpTool.InputSchema)
 }
 

internal/toolsets/vulnerability/deployments.go

@@ -35,7 +35,7 @@ type getDeploymentsForCVEInput struct {
 	FilterClusterID       string             `json:"filterClusterId,omitempty"`
 	FilterNamespace       string             `json:"filterNamespace,omitempty"`
 	FilterPlatform        filterPlatformType `json:"filterPlatform,omitempty"`
-	IncludeAffectedImages bool               `json:"includeAffectedImages,omitempty"`
+	IncludeDetectedImages bool               `json:"includeDetectedImages,omitempty"`
 	Cursor                string             `json:"cursor,omitempty"`
 }
 
@@ -55,7 +55,7 @@ type DeploymentResult struct {
 	Namespace       string   `json:"namespace"`
 	ClusterID       string   `json:"clusterId"`
 	ClusterName     string   `json:"clusterName"`
-	AffectedImages  []string `json:"affectedImages,omitempty"`
+	DetectedImages  []string `json:"detectedImages,omitempty"`
 	ImageFetchError string   `json:"imageFetchError,omitempty"`
 }
 
@@ -93,10 +93,16 @@ func (t *getDeploymentsForCVETool) GetName() string {
 func (t *getDeploymentsForCVETool) GetTool() *mcp.Tool {
 	return &mcp.Tool{
 		Name: t.name,
-		Description: "Get list of deployments where a specified CVE is detected in application" +
-			" or platform container images. Checks user workloads for vulnerabilities." +
-			" For complete CVE analysis, also check get_clusters_with_orchestrator_cve (Kubernetes components)" +
-			" and get_nodes_for_cve (node OS).",
+		Description: "Get list of deployments where a specified CVE" +
+			" is detected in application or platform container images." +
+			" USAGE PATTERNS:" +
+			" 1) When user asks 'Is CVE-X detected in my clusters?' (plural, general question):" +
+			" Call ALL THREE CVE tools (get_clusters_with_orchestrator_cve, get_deployments_for_cve, get_nodes_for_cve)" +
+			" for comprehensive coverage." +
+			" 2) When user asks specifically about 'deployments', 'workloads', 'applications'," +
+			" or 'containers': Use ONLY this tool." +
+			" 3) For single cluster queries (e.g., 'in cluster X'): First call list_clusters to get cluster ID," +
+			" then call ONLY this tool with filterClusterId.",
 		InputSchema: getDeploymentsForCVEInputSchema(),
 	}
 }
@@ -127,10 +133,10 @@ func getDeploymentsForCVEInputSchema() *jsonschema.Schema {
 		filterPlatformPlatform,
 	}
 
-	schema.Properties["includeAffectedImages"].Description =
-		"Whether to include affected image names for each deployment.\n" +
+	schema.Properties["includeDetectedImages"].Description =
+		"Whether to include detected image names for each deployment.\n" +
 			"WARNING: This may significantly increase response time."
-	schema.Properties["includeAffectedImages"].Default = toolsets.MustJSONMarshal(false)
+	schema.Properties["includeDetectedImages"].Default = toolsets.MustJSONMarshal(false)
 
 	schema.Properties["cursor"].Description = "Cursor for next page provided by server"
 
@@ -224,7 +230,7 @@ func (e *deploymentEnricher) enrich(
 			return
 		}
 
-		deployment.AffectedImages = images
+		deployment.DetectedImages = images
 	})
 }
 
@@ -309,7 +315,7 @@ func (t *getDeploymentsForCVETool) handle(
 		}
 	}
 
-	if input.IncludeAffectedImages {
+	if input.IncludeDetectedImages {
 		imageClient := v1.NewImageServiceClient(conn)
 		enricher := newDeploymentEnricher(imageClient, input.CVEName, defaultMaxFetchImageConcurrency)
 

internal/toolsets/vulnerability/deployments_test.go

@@ -425,7 +425,7 @@ func TestHandle_WithIncludeAffectedImages(t *testing.T) {
 			req := &mcp.CallToolRequest{}
 			input := getDeploymentsForCVEInput{
 				CVEName:               "CVE-2021-44228",
-				IncludeAffectedImages: testCase.includeImages,
+				IncludeDetectedImages: testCase.includeImages,
 			}
 
 			result, output, err := tool.handle(ctx, req, input)
@@ -442,12 +442,12 @@ func TestHandle_WithIncludeAffectedImages(t *testing.T) {
 
 				if testCase.includeImages {
 					assert.Empty(t, dep.ImageFetchError, "unexpected error for %s", dep.Name)
-					assert.Len(t, dep.AffectedImages, imageCount, "wrong image count for %s", dep.Name)
+					assert.Len(t, dep.DetectedImages, imageCount, "wrong image count for %s", dep.Name)
 
 					continue
 				}
 
-				assert.Empty(t, dep.AffectedImages, "should not have images when disabled")
+				assert.Empty(t, dep.DetectedImages, "should not have images when disabled")
 				assert.Empty(t, dep.ImageFetchError, "should not have error when disabled")
 			}
 		})
@@ -490,7 +490,7 @@ func TestHandle_ImageFetchPartialFailure(t *testing.T) {
 	req := &mcp.CallToolRequest{}
 	input := getDeploymentsForCVEInput{
 		CVEName:               "CVE-2021-44228",
-		IncludeAffectedImages: true,
+		IncludeDetectedImages: true,
 	}
 
 	result, output, err := tool.handle(ctx, req, input)
@@ -503,12 +503,12 @@ func TestHandle_ImageFetchPartialFailure(t *testing.T) {
 	// At least verify structure supports error field.
 	for _, dep := range output.Deployments {
 		if dep.Name == "deployment-1" {
-			assert.Len(t, dep.AffectedImages, 1)
+			assert.Len(t, dep.DetectedImages, 1)
 			assert.Empty(t, dep.ImageFetchError)
 		}
 		// dep-2 will have empty images since mock returns empty list.
 		if dep.Name == "deployment-2" {
-			assert.Empty(t, dep.AffectedImages)
+			assert.Empty(t, dep.DetectedImages)
 			assert.Empty(t, dep.ImageFetchError) // Empty list, not error in this mock.
 		}
 	}

internal/toolsets/vulnerability/nodes.go

@@ -73,10 +73,16 @@ func (t *getNodesForCVETool) GetName() string {
 func (t *getNodesForCVETool) GetTool() *mcp.Tool {
 	return &mcp.Tool{
 		Name: t.name,
-		Description: "Get aggregated node groups where a specified CVE is detected in node operating system packages" +
-			", grouped by cluster and OS image. Checks OS-level vulnerabilities on cluster nodes." +
-			" For comprehensive CVE coverage, also use get_clusters_with_orchestrator_cve (K8s components)" +
-			" and get_deployments_for_cve (workloads).",
+		Description: "Get aggregated node groups where a specified CVE is detected" +
+			" in node operating system packages, grouped by cluster and OS image." +
+			" USAGE PATTERNS:" +
+			" 1) When user asks 'Is CVE-X detected in my clusters?' (plural, general question):" +
+			" Call ALL THREE CVE tools (get_clusters_with_orchestrator_cve, get_deployments_for_cve, get_nodes_for_cve)" +
+			" for comprehensive coverage." +
+			" 2) When user asks specifically about 'nodes', 'hosts'," +
+			" or 'operating systems': Use ONLY this tool." +
+			" 3) For single cluster queries (e.g., 'in cluster X'): First call list_clusters to get cluster ID," +
+			" then call ONLY this tool with filterClusterId.",
 		InputSchema: getNodesForCVEInputSchema(),
 	}
 }