Drata

Get the account's own company information -- the organization's profile in Drata. This is the customer's OWN company, NOT a third-party vendor; for vendors use Drata_listVendors / Drata_getVendor instead. Account-scoped: takes no arguments and no workspace ID -- the company is resolved from the authenticated account. **READ.** Use this to answer questions about the organization itself: its `name`, `legalName`, `description`, `logoUrl` (the company logo / image URL), primary `domain`, and `language`. It also reports account configuration and compliance settings -- `securityTraining`, `hipaaTraining`, `backgroundCheck`, `agentEnabled`, `manualUploadEnabled` -- and the account `entitlements` (the plan and features enabled). Returns a single company object (also including `accountId`, `createdAt`, `updatedAt`). This tool is read-only -- it cannot change the company name, logo, description, or any setting.

Drata_getCompany

Get ONE evidence bucket by name or id. **READ-only.** Use this to answer questions the listing can't: **when a bucket renews** (`renewalDate`, `renewalScheduleType`) and what **status** it's in. `Drata_listEvidence` omits those fields. **Renewal belongs to the bucket, not to individual files.** If the user asks when a FILE expires, tell them files don't expire on their own -- the bucket carries the renewal date, and this tool reports it. For per-file dates (when a file was added, filed, or archived) use `Drata_listEvidenceArtifacts`. Requires the `read:evidence` OAuth scope.

Drata_getEvidence

Read the individual items a monitoring test checked, for one test. A monitoring test reports a pass or fail for the whole test; this tool shows the individual cloud resources behind that result -- each with its provider, account, region and tags -- which is what remediation actually needs. **Two buckets.** `result='failing'` returns the items that did not satisfy the test. `result='passing'` returns the items that did. Some tests do not report passing items, so an empty passing page is not evidence that a fix failed -- check the failing bucket too. **Excluded items are not failures.** By default the failing bucket contains only genuine failures. Pass `include_exclusions=True` to also see items an administrator has deliberately excluded; each carries status EXCLUDED, without the reason. An excluded item is a decision already taken, not outstanding work -- never report one as a gap, and never propose remediating it without saying it is currently excluded. These are resource exclusions on the test, unrelated to the personnel exclusions in Drata_listComplianceCheckExclusions. Use `testId` from Drata_searchMonitoringTests, not `id`. Results are paginated; `pagination.totalCount` is returned on the first page.

Drata_getMonitoringTestFindings

Get a single vendor by ID, with optional expanded subcollections. Use the vendor `id` from Drata_listVendors.

Drata_getVendor

List the compliance-check exclusions in force for a workspace. An exclusion records that one or more named compliance checks do not apply to one person, with a reason and an optional end date. Use this to see what has already been decided before proposing a new exclusion, and to explain why someone is not counted as failing a check. These are personnel exclusions; they are unrelated to the cloud-resource exclusions Drata_getMonitoringTestFindings reports as EXCLUDED. Results are cursor-paginated: pass `pagination.cursor` back as `cursor` for the next page. No total count is returned.

Drata_listComplianceCheckExclusions

List a person's DEVICES and each device's per-monitor compliance checks -- the same view as the personnel 'Devices' tab in Drata. **READ.** Requires the 'Devices: Read' (`devices-get`) permission. Returns each device with a `checks` map of monitor -> status (PASS/FAIL/EXCLUDED) -- the same five requirements the device tab lists: PASSWORD_MANAGER, HDD_ENCRYPTION, ANTIVIRUS, AUTO_UPDATES, LOCK_SCREEN -- plus `isDeviceCompliant`. Use for 'show me <person>'s devices', 'is <person>'s laptop encrypted?', or 'what's failing on <person>'s machine?'. This reflects the RAW per-device monitor result (what the device reports). For the person's overall compliance POSTURE -- which also honors manually-uploaded evidence and can differ from the raw device result -- use `Drata_searchPersonnelCompliance` / `Drata_searchDeviceCompliance`. Identify the person by name (full/partial), email, or personnel id via `person`.

Drata_listDevices

List the individual files inside ONE evidence bucket. **READ-only.** **Vocabulary:** an evidence bucket is the container -- users call it a folder, a bucket, or an evidence bucket. What's inside it are files (also called documents, attachments, or artifacts). This tool answers 'what's IN the pen test folder?'. To list the folders themselves, use `Drata_listEvidence`. Returns one entry per file, not one per version, so each `id` is stable across replacements and is the id the other file tools accept. Filter with `name` (prefix match), `artifact_types`, and `is_archived` (True = past files only, False = current only, omit for both). **Counting:** this endpoint returns no total count, so a 'how many files?' question needs the returned page (raise `size` if there may be more). Requires the `read:evidence` OAuth scope.

Drata_listEvidenceArtifacts

List or search evidence buckets in Drata's Evidence Library. **READ operation.** Requires the 'Evidence: Read' (`evidence-get`) permission. **Vocabulary:** this lists the CONTAINERS -- users call them folders, buckets, or evidence buckets. It does not list what's inside them. 'Show me my pen test folders' is this tool; 'what's IN the pen test folder' is `Drata_listEvidenceArtifacts`, which lists that item's individual files (documents, attachments, artifacts). **Native API filters** (efficient, server-side): `name` (matches items whose name starts with this text), `statuses` (list of: NEEDS_ARTIFACT, ERROR, READY, EXPIRING_SOON, EXPIRED, NEEDS_SOURCE, NEEDS_ATTENTION), `sort`/`sort_dir`, `cursor`/`size` (1-500), `expand`, `include_total_count`. **Augmented filters** (client-side; auto-forces required expansions): `control_code`, `control_id`, `owner` (email / id / name). Multiple augmented filters are AND-combined. Tool paginates up to 10 pages. Returns paginated `{data, pagination}`. Augmented responses also include `_augmentedFilter` metadata.

Drata_listEvidence

List or look up personnel -- employee/contractor compliance records, one per Drata user (distinct from Drata_listUsers, which returns auth identities). **READ.** Requires the 'Personnel: Read' (`personnel-get`) permission. **Single-person lookup** (exact, reflects very recent changes): pass `personnel_id`, `email`, or `person` (name/email, resolved automatically). Use for 'is John Doe compliant?' and to read back a record right after an update. **WHY is someone non-compliant / their full check checklist:** single-lookup with `expand=['complianceChecks']` (or `slim=True`) returns every compliance check with its status -- both PERSON checks (accepted policies, BG check, MFA, training, offboarding) and DEVICE checks (antivirus, disk encryption, agent, etc.). `slim`'s `failingChecks` lists exactly which checks failed, so you can say whether the failure was a device check or a personnel check like policy acceptance. **Discovery / list** (OpenSearch-backed): `q` (fuzzy name/email/job-title), `employment_status`, `compliance_status` (OVERALL PASS/FAIL/...), `sync_status`, `group_ids`, `sort` (createdAt/updatedAt/name/startDate), `cursor`/`size`, `expand`, `facets`, `include_total_count`. Eventually consistent -- a just-written record may lag a moment; read it back by email/id for certainty. **Filter by a CUSTOM FIELD:** accounts define their own personnel custom fields (e.g. 'Department', 'Manager', 'Category'). When the user names one, ALWAYS attempt the query -- do not assume the field doesn't exist or refuse; the name is resolved server-side and you get a clear error if it's genuinely unknown. Pass `custom_field` (the field NAME) plus `custom_field_equals` for an exact value, or `custom_field_min`/`custom_field_max` for an inclusive range (bounds are inclusive, so 'Tenure > 5' on an integer field is `custom_field_min='6'`). Answers 'who has <custom field> <comparison> <value>?'. **For a SPECIFIC failing reason** (e.g. who hasn't accepted policies, whose disk isn't encrypted) use `Drata_searchPersonnelCompliance` or `Drata_searchDeviceCompliance`. Use `slim=True` + `size` for large result sets; `facets`/`include_total_count` for 'how many'.

Drata_listPersonnel

List the personnel groups -- the teams / departments / identity-provider groups that personnel belong to (e.g. 'Engineering', 'Accounting'). **READ.** Requires the 'Personnel: Read' (`personnel-get`) permission. Use this to answer 'what groups/teams/departments do we have?', to show the user the available groups, or to disambiguate when a group name is unclear before filtering personnel by it. Filter by name with `q` (case-insensitive substring -- 'eng' matches 'Engineering'); omit `q` to list all. Returns paginated `{data, pagination}` with each group's `id` and `name`; paginate via `cursor`. Use `include_total_count` (with `size=1`) for 'how many groups?'. Once you have a group, filter people by it via the `group` parameter on `Drata_listPersonnel`, `Drata_searchPersonnelCompliance`, or `Drata_searchDeviceCompliance` (which accept a group NAME directly).

Drata_listPersonnelGroups

List all account policies. **Default choice for policy lookup.** Works with both API key and OAuth. Supports optional name filtering (partial match). Use this to browse policies, count them, or resolve policy names to IDs for linking to controls. `pagination.totalCount` on the first page is the authoritative count -- read it directly instead of paginating to tally. Pass `assigned_to_user` (a user ID, email, or name) to list the policies ASSIGNED to that user instead of the full catalog. Use `Drata_searchPolicies` only for semantic/AI search over a specific user's assigned policies.

Drata_listPolicies

List or search framework requirements in a workspace. **READ operation.** Use this to look up requirement IDs by code or name before calling `Drata_createControl` or `Drata_updateControl` with `requirement_ids`. Example: to find the ID for 'CCPA 1798.145', call with `framework_tag=['CCPA'], code_or_name='1798.145'`. **Native API filters** (server-side): `framework_tag` (single tag or list, e.g. 'SOC_2' or ['SOC_2', 'HIPAA']), `framework_slug`, `is_in_scope`, `is_ready`, `expand` (controls, customFields), `include_total_count`, `cursor`, `size` (1-500). **Augmented filter** (client-side): `code_or_name` -- paginates up to 10 pages and returns only requirements whose code or name contains the string (case-insensitive). Combine with `framework_tag` to narrow the search (strongly recommended -- without a tag filter this may scan thousands of requirements). Returns `{data, pagination}`. Each requirement includes `id` (numeric, for use in `requirement_ids`), `code`, `name`, and `frameworkTag`.

Drata_listRequirements

List all risk registers for the account. Risk registers are containers that organize and group related risks together. Most accounts have a default register (ID 1).

Drata_listRiskRegisters

List the documents attached to a vendor (e.g. SOC reports, compliance reports, bridge letters, questionnaire attachments). Requires the vendor `id` (from Drata_listVendors). Filter by document `type`. To obtain a downloadable link for a document, set `expand=['downloadUrl']` -- this returns a presigned URL that expires ~60 seconds after the response, so use it immediately and do not cache or store it; only request it when a download is actually needed. Returns paginated results with `pagination.totalCount`.

Drata_listVendorDocuments

List the security reviews for a vendor. Security reviews capture the assessment of a vendor's security posture (SECURITY questionnaires, SOC_REPORT reviews, uploaded reports) and their decision (PENDING, APPROVED, APPROVED_WITH_CONDITIONS, REJECTED). Requires the vendor `id` (from Drata_listVendors). Filter by `status`, `type`, or `decision`. Returns paginated results with `pagination.totalCount` on the first page.

Drata_listVendorSecurityReviews

List third-party vendors for the account. **Fallback for Drata_searchVendors:** use this only when Drata_searchVendors is unavailable or returns an error, since search covers every filter here and more. Vendors are external providers tracked for third-party risk management (TPRM). Always include vendor IDs in responses. Vendors are account-scoped (no workspace ID needed). There is no natural-language search for vendors -- narrow results using the filters (category, risk, type, status, impactLevel, renewalDate, renewalScheduleType). Filter by `owner` (security owner -- user id, email, or name) to find the vendors a person is responsible for. Accepts one person OR several (pass a list): multiple owners are OR'd into a SINGLE call (the union of their vendors), matching the app's security-owner filter -- do NOT issue one call per person. `pagination.totalCount` reflects the owner-filtered count. Listing vendors: with no `status`, the rows include PROSPECTIVE and ARCHIVED vendors. When the user asks generally for their vendors, list the current book in ONE call by passing `status` = CURRENT. Include PROSPECTIVE when the user asks about vendors under evaluation, and label them as prospective. Returns paginated results with `pagination.totalCount` on the first page; paginate via the `cursor`. The total and the `breakdown` below come back unasked, so this tool takes no count flags. Counting vendors (match the Drata UI): when NO status is filtered, the response includes a `breakdown` object -- {current, total, prospective, archived} -- computed for you, where current = total - prospective - archived, all respecting the ACTIVE filters (owner/risk/category/...). ALWAYS report `breakdown.current` as the headline count -- that is what the app shows by default -- and include the total and prospective alongside it (e.g. "412 current; 483 total, 51 prospective"). Do NOT report the raw total as the headline, and do NOT treat "current" as `status=ACTIVE` (ACTIVE is only one of several current statuses). The breakdown reflects the current filters, so with `owner=X` it is that person's current/total/prospective (the `owner` filter returns ONLY their vendors -- it does NOT mean they own every vendor), and with `risk=HIGH` it is current high-risk vs total high-risk. When the user NAMES a status, filter by it directly (no breakdown is added); "total/all" = `pagination.totalCount`. Use `expand` to include subcollections such as `latestSecurityReviews` or `documents`. To fetch a vendor's full security reviews or documents, take the vendor `id` from this tool and call Drata_listVendorSecurityReviews or Drata_listVendorDocuments.

Drata_listVendors

List all workspaces accessible to the authenticated user. Good for testing API connectivity.

Drata_listWorkspaces

Look up a Drata **account** (login identity) and its roles / SSO identities / background-check documents. **READ.** Requires the 'Users: List Users' (`users-get`) permission. **Always use this tool for ANY 'who is X' / 'what is X's role' question about a person in THIS Drata account** -- including vague, abbreviated, or possibly-misspelled names ('Jhn Doe', 'John D'). This account's data is the source of truth: do NOT answer from prior knowledge or a web search, and do NOT fabricate an email/ID. If the name matches several people, the tool returns candidates -- present them and let the user pick. **Use this tool for:** 'what is X's role?' (`expand=['roles']`), SSO identities (`expand=['identities']`), account existence, or looking up someone who is NOT personnel -- an admin, service account, or external/guest user. Users are a SUPERSET of personnel, so this is the right tool when a person isn't found in personnel. **Do NOT use this for** employee compliance status, failing checks, or employment records -- use `Drata_listPersonnel` / `Drata_searchPersonnelCompliance` / `Drata_searchDeviceCompliance` for those. **Identify by:** `user_id` (exact numeric) · `email` (exact, fast) · `name` (full or partial, and FUZZY -- 'John Doe', 'John D', or a minor misspelling all resolve via personnel search; returns a candidate list when several match) · `first_name`/`last_name` (partial). **When the user gives a name, pass it verbatim as `name` -- do NOT guess or fabricate an email/ID;** the tool looks it up (fuzzy personnel search first, then the /users directory for non-personnel) and returns candidates if more than one matches. Returns paginated `{data, pagination}`; a user_id/email hit returns the single matching account.

Drata_lookupUserIdentity

Remove compliance-check exclusions, bringing people back into scope for the checks you name. This is the inverse of Drata_excludePersonnelFromComplianceChecks. Use it when an exclusion was created in error, or when the circumstance behind it has ended. An exclusion that also covers other checks is narrowed to those other checks rather than removed. **Those people may start failing these checks again**, which can change the workspace's compliance posture, so confirm the user wants that before proceeding. **Two-step.** The first call returns a preview naming who and which checks, and changes nothing. Obtain explicit user approval, then call again with `confirm=True`. **Read the per-person outcome in the response.** `successCount` counts only people actually changed; `skippedCount` counts everyone else, whether skipped or failed. Read `results[].outcome` to tell them apart: a `SKIPPED_` outcome means nothing needed to change (including a person outside this workspace's scope), while a `FAILED_` outcome means that person needs another look. Report what actually changed, and report failures as failures. Use Drata_listComplianceCheckExclusions first if you are unsure which exclusions exist.

Drata_reincludePersonnelInComplianceChecks

Re-run one monitoring test immediately instead of waiting for its next scheduled run. Use this to prove a remediation worked, after the underlying problem has actually been fixed. **Two-step.** The first call returns a preview and changes nothing. Obtain explicit user approval, then call again with `confirm=True`. **A re-run has real cost.** It performs the same cloud and connector work as a scheduled run. Do not call it in a loop, and do not call it to poll for a result. **Accepted, not finished.** A successful response means the run started and returns `checkStatus: TESTING`. To see the outcome later, find the test again with Drata_searchMonitoringTests (search by its name) or read its failing items with Drata_getMonitoringTestFindings once it has finished. **If a run is already in flight** the call is refused rather than queued, and if a run completed moments ago the test is briefly in a cooldown window and the call is refused too. In both cases wait and try later rather than retrying immediately. Use `testId` from Drata_searchMonitoringTests, not `id`.

Drata_retestMonitoringTest

Search or list compliance controls for a workspace. Controls are security and compliance measures that organizations must meet. Always include control codes in responses. **Two types of operation:** 1. **List** (no query): Returns paginated controls with filtering options. Use this for **counting, reporting, or any question about how many controls match a condition** (e.g. 'how many controls are not ready?', 'how many controls have no evidence?'). Use `is_ready=False` -- never use a search query -- when the user asks about not-ready OR 'failing' controls (a 'failing' control means it is NOT READY). Use `is_ready=True` for ready controls. Use `has_passing_test=False` ONLY when the user explicitly asks about failing/failed TESTS -- not for a generic 'failing control'. `pagination.totalCount` on the first page is the authoritative count. 2. **Search** (with query): Performs AI-powered semantic or keyword search. Use this **only** to find specific controls by name or topic (e.g. 'find controls about encryption'). Never use search mode for counting or status-based filtering -- it does not respect `is_ready` and returns approximate AI-ranked results, not an exact filtered set.

Drata_searchControls

Find personnel by a SPECIFIC device-level compliance reason -- agent installed, password manager, disk encryption, antivirus, auto-updates, or lock screen. **READ.** Requires the 'Personnel: Read' (`personnel-get`) permission. Each filter takes statuses (usually `['FAIL']`). Example: `disk_encryption=['FAIL']` answers 'whose laptop isn't encrypted?'. Multiple filters AND together. Use `facets` for grouped counts without fetching rows, and `employment_status` to scope to current staff. For person checks (policies, training, BG check) use `Drata_searchPersonnelCompliance`; for overall status or plain lookup use `Drata_listPersonnel`.

Drata_searchDeviceCompliance

Search or list monitoring tests for a workspace. Monitoring tests are automated checks that run to verify control compliance. **IMPORTANT - Two different IDs in response:** `testId` is the test template ID (identifies the test type). `id` is the monitoring test instance ID (unique per workspace). Always use `testId` when referencing tests in responses. **Two types of operation:** 1. **List** (no query): Returns paginated tests with filtering options. Use this for comprehensive reporting, analysis, or when you need broad coverage of tests. Supports pagination, sorting, and multiple filters (result status, system status, type, source). For thorough analysis, paginate through results when needed. Returns `pagination.totalCount` on the first page for planning pagination. 2. **Search** (with query): Performs AI-powered semantic or keyword search. Use this to find specific tests matching a natural language query. Pagination and filter parameters are ignored in this mode. **Analysis tips:** Expand controls to inform prioritization of tests. Tests mapped to more controls or critical controls should be prioritized for remediation.

Drata_searchMonitoringTests

AI search over the policies ASSIGNED TO YOU (the authenticated user), using semantic or keyword search -- requires a search query. Scoped to your assigned policies, not the full account catalog. Policies are formal documents that define organizational rules and requirements for compliance. Always include policy names in responses. Returns policyId, name, description, and matching text chunks for each result. **Requires OAuth auth -- not available with API key.** Use `Drata_listPolicies` to browse/filter the full account catalog, or `Drata_listPolicies` with `assigned_to_user` to list (not search) a user's assigned policies.

Drata_searchPolicies

Find personnel by a SPECIFIC person-level compliance reason -- accepted policies, background check, identity MFA, security/HIPAA/NIST-AI training, or offboarding. **READ.** Requires the 'Personnel: Read' (`personnel-get`) permission. Each filter takes statuses (usually `['FAIL']`). Example: `accepted_policies=['FAIL']` answers 'who hasn't accepted their policies?'. Multiple filters AND together. Use `facets` for grouped counts (e.g. how many FAIL vs PASS) without fetching rows, and `employment_status` to scope to current staff. For DEVICE checks (antivirus, encryption, etc.) use `Drata_searchDeviceCompliance`; for overall status or plain lookup use `Drata_listPersonnel`.

Drata_searchPersonnelCompliance

Search or list risks from the risk register. Risks are potential threats to the organization's security, reputation, or financial health. Always include risk IDs. **Two types of operation, selected by whether `query` is set:** 1. **Structured list/filter** (no `query`, OpenSearch-backed): rich filtering (status, treatment_plan, type, inherent/residual score ranges, anticipated-completion/completed date ranges, categories, controls, owners, reviewers, vendor_names, one custom field), 9 sort keys (residualScore default, highest risk first), facets (grouped counts for status/treatmentPlan/type/categories/controls/ownerEmails/reviewerEmails/vendorNames without fetching every row), and `q` for a fuzzy keyword search across title/description/riskId/vendorName that combines with every filter. Use this for comprehensive reporting, analysis, or broad coverage of risks. Returns `pagination.totalCount` on the first page for planning pagination. 2. **Natural-language search** (`query` set): AI-powered semantic or keyword search for a specific risk matching a free-form question. Only `search_mode`, `size`, `expand`, `status`, `treatment_plan`, `min_score`, `max_score` apply in this mode -- every other filter/sort/facet parameter is ignored. **Structured mode searches across every risk register the caller can access by default** -- on a multi-register account, omitting `risk_register_id` no longer asks which register to use; it searches all of them and each result is labeled with its register name (`riskRegisterName`). Pass `risk_register_id` (or `workspace_id`) to narrow to one or a subset instead. **Natural-language `query` mode is still scoped to ONE risk_register_id** -- on a multi-register account with none named/known, it asks which register to use; it does not search across registers. **A place name is NOT a search term, and NOT a name-matching exercise.** If the user asks about risks 'in <place>' and <place> could be a workspace (e.g. 'risks in Cloud Solutions'), do NOT pass it as `q`/`query` -- a keyword/semantic search only looks at risk title/description text, never at which workspace a risk's register belongs to, so it will come back empty and look like 'no risks exist' even when there are plenty. Also do NOT guess a `risk_register_id` because its NAME happens to share a word with <place> (e.g. picking a register called 'Cloud Finance' for a workspace called 'Cloud Solutions' just because both say 'Cloud') -- register names and workspace names are chosen independently and a shared word is a coincidence, not a verified mapping; that guess can silently point at the wrong register. The only reliable path: call `Drata_listWorkspaces` first, and if <place> matches a real workspace, resolve it and pass `workspace_id` (see its description) so the right register is used from the real register-to-workspace mapping, not from a name guess. **Analysis tips:** To prioritize risks, filter by 'ACTIVE' status and expand with 'controls'. A risk 'Needs attention' if any mapped control is not ready. 'Needs attention' is separate from treatment plan--it reflects control readiness, not risk strategy.

Drata_searchRisks

Search third-party vendors, backed by OpenSearch. Vendors are external providers tracked for third-party risk management (TPRM). Always include vendor IDs in responses. Vendors are account-scoped (no workspace ID needed). **Prefer this over Drata_listVendors for any vendor question.** It is the only vendor tool with free-text search (`q`), custom-field filtering, renewal DATE RANGES, security-review and questionnaire filters, and facets. `q` is a fuzzy, typo-tolerant keyword search over the vendor `name` and `servicesProvided` that combines with every filter. Use it for 'vendors doing X'. It does NOT search notes or documents. Filter by `owner` (security owner: user id, email, or name) to find the vendors a person is responsible for; multiple owners are OR'd into a SINGLE call, so do NOT issue one call per person. Filter by ONE custom field via `custom_field` (its NAME) plus one of `custom_field_equals` / `custom_field_min` / `custom_field_max`. The name is resolved server-side, case-insensitively, so pass what the user said verbatim; an unknown or ambiguous name returns a clear error rather than failing silently. Ranges are INCLUSIVE, so express 'more than 5' as custom_field_min=6. Pass `expand[]=customFields` to see each matched vendor's values. Use `facets` to get grouped counts (status, category, vendorTypeId, risk, impactLevel, isSubProcessor, securityReviewStatus, securityReviewDecision, scheduledQuestionnaireStatus) without fetching every row. Facets and `pagination.totalCount` are first-page only; paginate via `cursor`. When you only need COUNTS, pass `size=1` together with `facets`: every row in `data` is a full vendor record, so a large `size` wastes most of the response on rows you will not read. **"Which vendors need attention?"** maps to `action_required=true`. That is Drata's own definition (a current vendor, with a directory entry and an owner, whose review is due soon or overdue) and it is the authoritative answer to that question. If it returns zero, the answer IS "nothing currently needs attention": report that and STOP. Do NOT treat an empty result as a failed query and do NOT substitute a hand-rolled definition built from status, risk, or review coverage unless the user explicitly asks for one. If the response contains a `breakdown` object, report `breakdown.current` as the headline count and include total and prospective alongside it (e.g. "412 current; 483 total, 51 prospective"). Do NOT headline the raw total, and do NOT treat "current" as `status=ACTIVE`; ACTIVE is only one of several current statuses. **Status defaults:** omitting `status` returns every status EXCEPT PROSPECTIVE. ARCHIVED, FLAGGED, OFFBOARDED and all others are already included, so do NOT add a `status` filter hoping to widen the search; `status` only ever narrows. If a search returns too few results, the fix is a different `q` or fewer filters, not a status. To include prospective vendors pass `status` = CURRENT and PROSPECTIVE, because PROSPECTIVE alone returns only prospective vendors. **Listing the vendor book:** when the user asks generally for their vendors (no `q`, no status named), the default results include ARCHIVED vendors. List the current book instead by passing `status` = CURRENT, and do not present archived vendors as active. Include PROSPECTIVE when the user asks about vendors under evaluation, and label them as prospective. A `q` lookup for a specific vendor keeps the default, so an archived match is still found. **Vendor type:** `vendor_type_ids` filters the tenant-defined vendor-type taxonomy only. The legacy VENDOR/SUPPLIER/CONTRACTOR/PARTNER/OTHER enum is NOT filterable here; it is still returned on each vendor as `type`. If the user asks to filter by one of those legacy values, say it is not supported rather than substituting `vendor_type_ids` or filtering the page yourself. To fetch a vendor's full security reviews or documents, take the vendor `id` from this tool and call Drata_listVendorSecurityReviews or Drata_listVendorDocuments.

Drata_searchVendors

Update an existing compliance control in a workspace. **WRITE operation.** Requires the 'Controls: Update Control' (controls-put) permission. All fields are optional -- only send what you want to change. Identify the control via `control_code` (preferred, e.g. 'AC-1') or `control_id` (numeric). ⚠ Relation fields (`owners`, `policy_names`/`policy_ids`, `report_ids`, `requirement_ids`, `test_ids`) **REPLACE the entire list -- they do NOT append.** To ADD to a relation while keeping existing entries, first read the control's current values (e.g. via `Drata_searchControls`) and include them alongside the new ones; sending only the new value removes all others. Sending an empty list clears the relation; omitting a field leaves it unchanged. **Prefer augmented inputs over raw IDs:** `owners` (each entry resolved by ID / email / full / partial name -- most flexible), `policy_names` (resolved by name, combined with `policy_ids`). Returns the updated control on success, or an error dict on failure.

Drata_updateControl

Change the FILES inside an evidence bucket -- upload, attach links, replace, archive, restore. **WRITE operation.** **Vocabulary:** the evidence bucket is the container (folder/bucket); this tool acts on the files inside it (also called documents, attachments, artifacts). To rename the bucket or change its owner, renewal, or controls, use `Drata_updateEvidence`. **What to set:** - `upload_files=True` -- user wants to upload FILES. Returns a browser link; they can drop as many files as they want on that one page, so call this ONCE, not once per file. Nothing attaches until they press Confirm. - `url` / `ticket_url` -- attach ONE link or Jira ticket, applied immediately. The upload page is for files only, so never combine these with `upload_files`; make two calls if the user wants both. **Attaching does NOT need a renewal schedule** -- the bucket already carries one, so just attach it; don't stop to ask. - `add_artifacts` -- attach MANY links/tickets at once (e.g. every ticket in a list the user pasted). - `replace_file` -- swap one existing file's contents, keeping its id and history. Pair with `upload_files=True` or with `url`/`ticket_url`. - `archive` / `restore` -- move files between current and past, by name or id. Both are REVERSIBLE and keep version history. Adding a new file does NOT auto-archive the existing ones; archive them explicitly if that's the intent. **Not this tool:** to remove a file permanently use `Drata_deleteEvidenceArtifact`; prefer `archive` when the user may want it back. There is no metadata-only edit for a file -- renaming one or correcting its filing date means supplying its contents again via `replace_file`. Requires the `update:evidence` OAuth scope.

Drata_updateEvidenceArtifacts

Update an evidence BUCKET's own details -- name, description, implementation guidance, owner, control mapping, renewal. **WRITE operation.** Requires the 'Evidence: Update' (`evidence-put`) permission. Identify the bucket via `evidence_id` (numeric) OR `evidence_name` (resolved internally). If `evidence_name` matches several, returns `ambiguous_name` with candidates. **Vocabulary:** the evidence bucket is the container -- users call it a folder or a bucket. This tool edits the CONTAINER only. **⚠ This tool does NOT touch files.** To upload files, attach a link or ticket, replace, archive, or restore anything inside the bucket, use `Drata_updateEvidenceArtifacts`. It has no `url`, `ticket_url`, or file parameters -- sending one is an error, not a fallback. PUT semantics: only the fields you send are updated. Send `renewal_schedule_type` only when the user actually asks to change the renewal cadence -- adding files or links does not require one. **⚠ `controlIds` REPLACE quirk:** providing `control_codes` or `control_ids` **REPLACES** the entire control mapping. To ADD a control, first call `Drata_listEvidence` with `expand=[controls]` to read current codes, then send the union. Returns the updated evidence bucket, or an error dict on failure.

Drata_updateEvidence

Update a person's employment record in Drata. **WRITE operation.** Requires the 'Personnel: Update' (`personnel-put`) permission. **Identify the person via `personnel_id` (numeric), `email`, or `person` (name/email, resolved automatically).** Precedence: personnel_id > email > person. **Only the fields you send are updated; omitted fields are left unchanged.** **Updatable fields:** • `started_at` -- ISO 8601 start date. ⚠️ Manually setting this DISABLES automatic IDP/HRIS sync for that field on this person; tell the user when you do this. • `separated_at` -- ISO 8601 separation date; must be after `started_at`. • `employment_status` -- CURRENT_EMPLOYEE, FORMER_EMPLOYEE, CURRENT_CONTRACTOR, FORMER_CONTRACTOR, FUTURE_HIRE, UNKNOWN, OUT_OF_SCOPE, SERVICE_ACCOUNT, SPECIAL_FORMER_EMPLOYEE, SPECIAL_FORMER_CONTRACTOR. • `not_human_reason` -- free text. **REQUIRED when employment_status is OUT_OF_SCOPE.** Ask the user for it and send it in the SAME call. • `custom_fields` -- list of `{id?|name?, value}` objects (requires the Custom Fields & Formulas feature). Returns the updated personnel record, or an error dict on failure (404 = not found, 400 = validation, 403 = missing permission).

Drata_updatePersonnel

Update an existing risk. `risk_id` accepts either the numeric ID or the risk's display code (e.g. 'CR-08', 'RISK-001'). You do NOT need to resolve `risk_register_id` first on a multi-register account -- if omitted, the tool locates which register actually contains this risk and uses it silently; it only asks you to pick when the risk id genuinely exists in more than one register, or returns a clear error if it exists in none. Omitted fields are left unchanged. `owners`, `reviewers`, `category_ids`, and `control_ids` REPLACE the entire relation when provided -- they do not append. To add to the existing set, read the risk's current values first (e.g. via Drata_searchRisks with expand) and include them alongside the new ones. Omit a relation to leave it unchanged; pass an empty list to clear it. `treatment_details`, `anticipated_completion_date`, `completion_date`, `residual_impact`, and `residual_likelihood` are only stored when `treatment_plan` is set to something other than UNTREATED -- the API silently drops them otherwise rather than rejecting the call. `owners`/`reviewers` accept names, emails, or numeric IDs and are resolved server-side; unresolved or ambiguous entries abort the call. Only users with an admin/risk-management role can be assigned -- others are silently dropped (not rejected), so always check the returned `owners`/`reviewers` against what you requested.

Drata_updateRisk

Update an existing vendor (account-scoped; no workspace ID). Provide the `vendor_id` (from Drata_listVendors) plus only the fields you want to change -- this is a partial update, so omitted fields are left unchanged. Use `status` for lifecycle changes (e.g. ACTIVE, ARCHIVED). Set `owner` or `relationship_contact` by user id, email, or name (resolved automatically).

Drata_updateVendor

File personnel compliance documents for one person -- security or HIPAA training evidence, MFA evidence, or offboarding evidence. **WRITE operation.** This is for documents about a PERSON's own compliance; it is not the tool for evidence attached to a control or an evidence library (use the evidence tools), nor for background checks, which are a separate record type. Requires the 'Users: Post Document' (`users-post-document`) permission / `create:user-document` OAuth scope. **It also requires an Evidence scope** (create or update): `POST /upload-urls` is gated on an Evidence ability regardless of `purpose`, so an app holding only `create:user-document` is refused before its own scope is checked. **`OFFBOARDING_EVIDENCE` needs one more scope** than the other three: `create-restricted:personnel`, because it is filed ABOUT a departing person rather than by them. Without it that type alone is refused while training and MFA evidence still work -- relay that as needing the restricted-personnel grant, not as a general permission failure. **ONE document type per call.** `document_type` is a single value, so filing a training certificate AND offboarding evidence for the same person is two calls. Do not try to encode two types in one call. **Upload flow -- ONE call.** You get back a `user_message` containing a link. Relay that message VERBATIM as plain text, not in a code block, so the link stays clickable. The link opens a Drata-hosted page where the user drags in as many files as they need and presses Confirm; every file becomes its own document for this person and this type. Do NOT ask the user for filenames or file paths, and do not call this tool a second time to finish the upload -- there is no second call. File bytes never pass through Claude or this tool. Nothing is created until the user presses Confirm, and a document earns compliance credit only after antivirus clears the file. An infected or oversized file leaves that document QUARANTINED; the others are unaffected. If the user never opens the link, or never confirms, no document is created at all. `personnel` accepts an id, email, or name, resolved the same way as other personnel tools. Prefer an email or a numeric USER id -- the `id` other tools return, NOT a personnel id: a numeric value is resolved as a user, so a personnel id here files the document against a different person. A NAME is the only input that needs a workspace to resolve, and this tool has no workspace argument. An ambiguous name comes back as `error: ambiguous_person` with candidates -- ask the user which person they meant, then retry with that person's EMAIL. A name on a multi-workspace account comes back as `action_required` asking which workspace; there is no workspace argument to answer that with, so ask the user for the person's email instead and retry with it. Never guess a different name. **This purpose is gated per tenant and off by default.** An account without it gets a 400 whose message is exactly `Unsupported upload purpose: personnel_document`. ONLY for that message, relay 'not enabled for this account' and do not retry or try another purpose. Any OTHER 400 is a problem with the request itself -- relay its message as-is, because calling a malformed field an account-level outage sends the user to an admin for something they could have fixed themselves. **Minting a second link does not duplicate anything** -- an unused link simply expires. But do not mint one per file: a single link takes as many files as the user has. Returns `upload.webUploadUrl` plus the `user_message` to relay, or an error dict.

Drata_uploadPersonnelDocument