Add and clarify optional parameters for tools

Author: garrett-mccutcheon

src/operations/common/descriptions.ts

@@ -2,7 +2,7 @@
 // This file provides centralized, consistent descriptions for commonly used parameters
 // across all operations files, ensuring uniformity and maintainability.
 
-export const PAGE_SIZE_DESCRIPTION = `Controls the maximum number of tests returned in a single response.
+export const PAGE_SIZE_DESCRIPTION = `Controls the maximum number of results returned in a single response.
 Allowed values: 1–100. Default is 10.`;
 
 export const PAGE_CURSOR_DESCRIPTION = `A marker or pointer telling the API where to start fetching items for the

src/operations/documents.ts

@@ -13,11 +13,27 @@ import {
 } from "./common/imports.js";
 
 // 2. Input Schemas
-const DocumentsInput = createConsolidatedSchema({
-  paramName: "documentId",
-  description: DOCUMENT_ID_DESCRIPTION,
-  resourceName: "document",
-});
+const DocumentsInput = createConsolidatedSchema(
+  {
+    paramName: "documentId",
+    description: DOCUMENT_ID_DESCRIPTION,
+    resourceName: "document",
+  },
+  {
+    frameworkMatchesAny: z
+      .array(z.string())
+      .describe(
+        "Filter documents by framework IDs. Returns documents that belong to any of the specified frameworks, e.g. ['soc2', 'iso27001', 'hipaa']",
+      )
+      .optional(),
+    statusMatchesAny: z
+      .array(z.string())
+      .describe(
+        "Filter documents by status. Possible values: Needs document, Needs update, Not relevant, OK.",
+      )
+      .optional(),
+  },
+);
 
 const DocumentResourcesInput = z.object({
   documentId: z.string().describe(DOCUMENT_ID_DESCRIPTION),
@@ -48,7 +64,7 @@ export const DocumentsTool: Tool<typeof DocumentsInput> = {
 export const DocumentResourcesTool: Tool<typeof DocumentResourcesInput> = {
   name: "document_resources",
   description:
-    "Access document-related resources including controls, links, and uploads. Specify resourceType to get the specific type of resource associated with a document. Use this to explore what controls are linked to a document, what external references exist, or what files are attached.",
+    "Access document-related resources including controls, links (i.e. hyperlinks), and uploads. Specify resourceType to get the specific type of resource associated with a document. Use this to explore what controls are linked to a document, what external references exist, or what files are attached (including the download link for those files).",
   parameters: DocumentResourcesInput,
 };
 

src/operations/integrations.ts

@@ -29,7 +29,7 @@ const IntegrationResourcesInput = z.object({
   resourceKind: z
     .string()
     .describe(
-      "Resource kind to operate on, e.g. 'ec2-instances' or specific resource kind identifier (required for get_kind_details, list_resources, get_resource)",
+      "Resource kind to operate on, e.g. 'EC2Instance' or specific resource kind identifier (required for get_kind_details, list_resources, get_resource)",
     )
     .optional(),
   resourceId: z

src/operations/people.ts

@@ -8,12 +8,22 @@ import {
 } from "./common/imports.js";
 
 // 2. Input Schemas
-const PeopleInput = createConsolidatedSchema({
-  paramName: "personId",
-  description:
-    "Person ID to retrieve, e.g. 'person-123' or specific person identifier",
-  resourceName: "person",
-});
+const PeopleInput = createConsolidatedSchema(
+  {
+    paramName: "personId",
+    description:
+      "Person ID to retrieve, e.g. 'person-123' or specific person identifier. If provided, returns the specific person, and no other parameters may be provided. If omitted, lists all people with optional filtering and pagination. ",
+    resourceName: "person",
+  },
+  {
+    taskStatusMatchesAny: z
+      .array(z.string())
+      .describe(
+        "Filter people by task status. Possible values: COMPLETED (Task is completed), IN_PROGRESS (Task is in progress), FAILED (Task failed), NOT_STARTED (Task is not started)",
+      )
+      .optional(),
+  },
+);
 
 // 3. Tool Definitions
 export const PeopleTool: Tool<typeof PeopleInput> = {

src/operations/risks.ts

@@ -12,24 +12,30 @@ const RisksInput = createConsolidatedSchema(
   {
     paramName: "riskId",
     description:
-      "Risk scenario ID to retrieve, e.g. 'risk-scenario-123' or specific risk identifier",
+      "Risk scenario ID to retrieve, e.g. 'risk-scenario-123' or specific risk identifier. If provided, returns the specific risk scenario, and no other parameters may be provided. If omitted, lists all risk scenarios with optional filtering and pagination.",
     resourceName: "risk scenario",
   },
   {
     categoryMatchesAny: z
       .string()
       .optional()
       .describe(
-        "Filter by risk category. Example: Access Control, Cryptography, Privacy, etc.",
+        "Filter by risk category. Example: Access Control, Cryptography, Privacy, etc. Use 'Uncategorized' for risks that don't have a category.",
       ),
+    reviewStatusMatchesAny: z
+      .array(z.string())
+      .describe(
+        "Filter risk scenarios by review status. Possible values: PENDING, APPROVED, REJECTED",
+      )
+      .optional(),
   },
 );
 
 // 3. Tool Definitions
 export const RisksTool: Tool<typeof RisksInput> = {
   name: "risks",
   description:
-    "Access risk scenarios in your Vanta account. Provide riskId to get a specific risk scenario, or omit to list all risks with optional category filtering. Returns risk details, assessments, and mitigation strategies for compliance reporting.",
+    "Access risk scenarios in your Vanta account. Provide riskId to get a specific risk scenario, or omit to list all risks with optional filtering and pagination. Returns risk details, impact assessments, and mitigation strategies for compliance reporting.",
   parameters: RisksInput,
 };
 

src/operations/tests.ts

@@ -12,12 +12,30 @@ import {
 } from "./common/imports.js";
 
 // 2. Input Schemas
-const TestsInput = createConsolidatedSchema({
-  paramName: "testId",
-  description:
-    "Test ID to retrieve, e.g. 'test-123' or specific test identifier",
-  resourceName: "test",
-});
+const TestsInput = createConsolidatedSchema(
+  {
+    paramName: "testId",
+    description:
+      "Test ID to retrieve, e.g. 'test-123' or specific test identifier. If provided, returns the specific test, and no other parameters may be provided. If omitted, lists all tests with optional filtering and pagination.",
+    resourceName: "test",
+  },
+  {
+    statusFilter: z
+      .string()
+      .describe(
+        "Filter tests by test status. Possible values: OK (Test passed), DEACTIVATED (Test is deactivated), NEEDS_ATTENTION (Test failed), IN_PROGRESS (Test is in progress), INVALID (Test is invalid), NOT_APPLICABLE (Test is not applicable)",
+      )
+      .optional(),
+    frameworkFilter: z
+      .string()
+      .describe("Filter tests by framework. Provide framework ID.")
+      .optional(),
+    integrationFilter: z
+      .string()
+      .describe("Filter tests by integration. Provide integration ID.")
+      .optional(),
+  },
+);
 
 const ListTestEntitiesInput = createIdWithPaginationSchema({
   paramName: "testId",
@@ -29,7 +47,7 @@ const ListTestEntitiesInput = createIdWithPaginationSchema({
 export const TestsTool: Tool<typeof TestsInput> = {
   name: "tests",
   description:
-    "Access security tests in your Vanta account. Provide testId to get a specific test, or omit to list all tests. Returns test IDs, names, types, schedules, current status, and detailed configuration for compliance monitoring.",
+    "Access continuous monitoring tests in your Vanta account. Provide testId to get a specific test, or omit to list all tests. Returns test IDs, names, types, schedules, current status, and detailed configuration for compliance monitoring.",
   parameters: TestsInput,
 };
 

src/operations/vulnerabilities.ts

@@ -8,12 +8,46 @@ import {
 } from "./common/imports.js";
 
 // 2. Input Schemas
-const VulnerabilitiesInput = createConsolidatedSchema({
-  paramName: "vulnerabilityId",
-  description:
-    "Vulnerability ID to retrieve, e.g. 'vulnerability-123' or specific vulnerability identifier",
-  resourceName: "vulnerability",
-});
+const VulnerabilitiesInput = createConsolidatedSchema(
+  {
+    paramName: "vulnerabilityId",
+    description:
+      "Vulnerability ID to retrieve, e.g. 'vulnerability-123' or specific vulnerability identifier. If provided, returns the specific vulnerability, and no other parameters may be provided. If omitted, lists all vulnerabilities with optional filtering and pagination.",
+    resourceName: "vulnerability",
+  },
+  {
+    externalVulnerabilityId: z
+      .string()
+      .describe(
+        "Filter vulnerabilities by external vulnerability ID (e.g. CVE-2024-1234). Returns vulnerabilities that match the provided external vulnerability ID.",
+      )
+      .optional(),
+    severity: z
+      .string()
+      .describe(
+        "Filter vulnerabilities by severity. Possible values: LOW (Low severity), MEDIUM (Medium severity), HIGH (High severity), CRITICAL (Critical severity)",
+      )
+      .optional(),
+    integrationId: z
+      .string()
+      .describe(
+        "Filter vulnerabilities by integration ID. Returns vulnerabilities that are associated with the specified integration.",
+      )
+      .optional(),
+    slaDeadlineAfter: z
+      .string()
+      .describe(
+        "Filter vulnerabilities by SLA deadline after the specified date. Returns vulnerabilities that have an SLA deadline after the specified date. Date should be formatted as YYYY-MM-DD.",
+      )
+      .optional(),
+    slaDeadlineBefore: z
+      .string()
+      .describe(
+        "Filter vulnerabilities by SLA deadline before the specified date. Returns vulnerabilities that have an SLA deadline before the specified date. Date should be formatted as YYYY-MM-DD.",
+      )
+      .optional(),
+  },
+);
 
 // 3. Tool Definitions
 export const VulnerabilitiesTool: Tool<typeof VulnerabilitiesInput> = {