# Usage examples

> Prompts drawn from how clients really use the Tidal Control MCP server, covering documents, controls, risks, assets, vendors, tasks, tests and insights.

Source: https://tidalcontrol.com/docs/ai/mcp/examples

These prompts are drawn from how clients actually use the MCP server. Each one is something you can paste to your AI assistant once the [MCP server](/docs/ai/mcp) is connected.

## How clients use the MCP server

These examples are based on real usage patterns from our clients. Each one is a natural-language prompt you can give your AI assistant once the [MCP server is connected](/docs/ai/mcp). Most traffic today comes from Claude Code and Claude on the web, with the rest from Codex and other MCP-capable clients.

> **info:**

The prompts are illustrative. You don't pick tools yourself. You describe your goal in plain language and the assistant sequences the right tools. The tool names below are shown only so you can see what's happening under the hood.

## Documents and policies

Document work is the most common use, by a wide margin. Clients find, read, and update policies and procedures without leaving their assistant.

**Find and read a document**

> "Find our network segmentation policy and show me its current content."

The assistant locates the document with `documentFind`, then reads the full text with `documentGetContent`. For meaning-based questions like *"where do we describe our incident-response timeline?"*, it uses `documentSearch` (semantic search) instead.

**Read several documents at once**

> "Read our change management policy and our secure development policy, and tell me where they contradict each other."

The assistant pulls both texts in a single call with `documentGetContentBatch` rather than fetching them one by one. This is the usual opening move for consistency checks across a set of policies.

**Update a section of a document**

> "In the password policy, change the minimum length requirement from 8 to 12 characters, then show me the result."

The assistant reads the current text with `documentGetContent`, applies a precise change with `documentEdit`, and reads the document back so you can see what landed. Reading back after an edit is the single most common two-step pattern on the server.

> **info:**

Documents that are the **approved content of a policy** can't be edited over MCP. The assistant will tell you which policy is involved. Amend the draft from the portal's policy editor instead.

**Work on a draft without touching the approved version**

> "Create a draft of the legal and contractual requirements register, rewrite the scope section, and leave the approved version alone."

The assistant derives an editable draft with `documentClassificationCreateDraft`, then edits that draft with `documentEdit`. The approved version stays untouched until you sign the draft off.

**Check and approve policy coverage**

> "Which document is our access control policy, and has it been approved?"

Uses `documentClassificationFind` to show which document fulfils that policy and its approval state. To sign it off (*"Approve the access control policy classification."*), the assistant calls `documentClassificationUpdate`.

**See what your framework still requires**

> "Which documents does ISO 27001 require that we don't have yet?"

Uses `requiredDocumentFind` to list the required documents for your adopted frameworks and show which ones are still missing. This is a common first question before a certification round.

## Compliance controls

Controls can be searched by topic, by the framework requirement they satisfy, and by the work attached to them.

**Find controls by topic**

> "List our access-control requirements that apply to remote workers."

The assistant calls `controlFind` with the relevant search text and category.

**See which controls mitigate a risk**

> "Which controls do we have that mitigate the risk of unauthorised remote access?"

The assistant finds the risk with `riskFind`, then lists the controls linked to it with `controlFind`.

**Check what's happening on a control**

> "Show me control C.06 and every task, review and execution attached to it."

The assistant reads the control with `controlFind` and lists the linked work with `activityFind`. Moving from a control to its activities is one of the most widely used sequences on the server.

**Count coverage**

> "How many controls do we have tagged for internal audit, and how many are linked to risk R.IT.15?"

Uses `controlCount`, which answers sizing questions without pulling the full list back into the conversation.

**Check which frameworks you've adopted**

> "Which frameworks have we adopted, and how far along is each one?"

Uses `frameworkFind` for the adopted set. Clients typically ask this before planning a sequence, for example whether to take on NIS2 before or after an AI standard.

**Map controls to clauses**

> "Which ISO 27001 Annex A references are currently marked out of scope?"

Uses `referenceFind` to list clause references and their state, and `referenceCount` to count the references attached to a given control. Useful when you're building a Statement of Applicability or a clause coverage matrix.

## Risks and risk assessments

In Tidal Control a **risk** is the threat you're tracking; a **risk assessment** records its impact and likelihood scores over time.

**Add a new risk**

> "Add a new risk for the SCADA upgrade project: an external attacker reaching OT network zone 3."

The assistant calls `riskCreate` with the name and description.

**Score a risk**

> "Assess that risk: impact 4, likelihood 3, treatment reduce."

The assistant calls `riskAssessmentCreate` to record the impact, likelihood, residual scores, and treatment.

**Revise a score after remediation**

> "We've finished the patch cycle on the unpatched HMI firmware. Lower its residual likelihood from high to medium."

The assistant locates the current assessment with `riskAssessmentFind`, then updates the score with `riskAssessmentUpdate`.

**Review risks by residual level**

> "Show me all risks with a high residual rating in the vendor-access category."

Uses `riskFind` filtered by residual risk level. For questions about the shape of the register rather than its contents (*"how many risks carry a treatment other than reduce?"*), the assistant uses `riskCount`.

**Find risks that still need a score**

> "Which risks have no current assessment? Read each one, then tell me what's missing."

The assistant lists the register with `riskFind` and reads each risk's score history with `riskAssessmentFind`. Clients use this to find register entries that were never valued.

**Link a control to a risk**

> "Link our ISMS documentation control to the risk about missing documentation."

Uses `riskAddControls` to record which controls mitigate which risk, so the treatment decision has something behind it.

## Assets

Assets can be created, rated, and linked to the risks and controls that apply to them.

**Review the register**

> "List every active asset and tell me which ones have no owner assigned."

Uses `assetFind`, the most widely used tool in this area. `assetCount` answers the sizing version of the same question.

**Add a missing asset**

> "Add the container registry I found on the Azure network view: it isn't in our inventory yet."

Uses `assetCreate`, then `assetUpdate` to fill in the details once the record exists. Clients most often reach for this after a review turns up something the register missed.

**Set CIA ratings**

> "Set the confidentiality, integrity, and availability of the customer database to 5, 4, and 5."

The assistant calls `assetUpdate` with the CIA scores.

**Set recovery objectives**

> "Give the billing platform a 4-hour RTO and a 1-hour RPO."

Uses `assetUpdate` to set the recovery time and point objectives.

**Adjust a group of assets**

> "For every cloud-resource asset, set the availability rating to 4."

Uses `assetUpdate` once per matching asset.

## Vendors

Vendors can be added, assessed, and checked for the evidence you're supposed to hold on them.

**Add and assess a vendor**

> "Add Acme Industrial as a new vendor (they supply the network switches for our OT environment) and start a vendor assessment with medium criticality and EU jurisdiction."

The assistant creates the vendor with `vendorCreate`, then scaffolds the assessment with `vendorAssessmentCreate`.

**Fill in an assessment that's already been scaffolded**

> "Open the draft assessment for our password manager and record the agreed risk values."

The assistant reads the current assessment with `vendorAssessmentFind` before writing to it with `vendorAssessmentUpdate`, so manual edits already in the record aren't overwritten. Read before write is how clients use this pair in practice.

**Audit vendor completeness**

> "Which vendors have no approved risk assessment, and which of their mandatory documents are missing?"

The assistant lists vendors with `vendorFind`, checks their assessments with `vendorAssessmentFind`, and uses `evidenceFind` to see which supporting documents are on file. A vendor's risk rating and data-processing level determine which documents are mandatory.

**Raise an issue from an assessment**

> "Flag the missing processing agreement for this vendor as an issue and set a response deadline."

The assistant creates the finding with `activityCreateIssue` while it's still in the assessment. Moving straight from an assessment into a tracked issue is a common way clients close the loop.

## Tasks and activities

Tidal Control's work items are **issues** (findings and gaps), **assessments** (reviews and audits), and **executions** (scheduled control runs).

**Review open findings**

> "Show me all open issues created in the last 30 days."

Uses `activityFind` filtered by type and date range. `activityCount` gives the totals when you only want the numbers.

**Find overdue control runs**

> "Which control executions are overdue?"

Uses `activityFind` filtered by execution type and overdue status.

**Turn findings into linked tasks**

> "Create issue tasks for each of these 12 audit findings and link them to control AC-01."

The assistant calls `activityCreateIssue` for each finding and links them with `activityIssueAddControls`. Creating a finding and immediately linking it to the control it belongs to is the standard shape of this work.

**Set owners and deadlines on findings**

> "Assign the CTO as owner of the audit finding about management roles, and set the due date to the end of next month."

Uses `activityUpdateIssue` for the owner and the deadline, so the register reflects the corrective action plan.

**Schedule and close control runs**

> "Create a monthly follow-up round for corrective actions, and close the physical access review with the outcome recorded."

The assistant schedules the recurring work with `activityCreateExecution`, links it to the control with `activityExecutionAddControls`, and closes a finished run with `activityCloseExecution` once the outcome is documented.

**Record what happened**

> "Add a note to this finding saying the processing agreement request went out in writing on the 12th."

Uses `commentAdd`. To read the discussion back, the assistant uses `commentFind`.

**Check the plan**

> "Which plans is our annual governance phase attached to?"

Uses `planFind` to show the plans a control or activity sits in.

## Automated tests

> "Which automated tests are currently failing, and which controls do they cover?"

Uses `testFind` filtered by status, then `controlFind` for the controls behind them. For pass/fail history over time, the assistant follows up with `testResultFind`.

> "Has any of our integration tests ever run?"

Auditors ask this one directly. `testFind` lists the configured tests and `testResultFind` shows whether results exist, which tells you where manual evidence is still needed.

## Insights and KPIs

Six summary tools give you the state of the programme without reading a single record. They're read-only and cheap, which makes them a good opening prompt before a meeting or an audit.

**Get a compliance snapshot**

> "Give me a summary of our current ISO 27001 status, including open tasks and control effectiveness."

Uses `insightsFrameworkStatistics` for posture per framework. The other five cover assets (`insightsAssetsKpi`), vendors (`insightsVendorsKpi`), personnel (`insightsPersonnelKpi`), activities (`insightsActivityStatistics`), and automated tests (`insightsTestStatistics`).

**Size a gap before you dig in**

> "How much of our asset register is assessed and compliant?"

Uses `insightsAssetsKpi` to return the aggregate counts, so you can decide whether the detail is worth pulling.

## People and context

Assistants orient themselves before they write anything, and you can ask these questions directly.

**Check which tenant you're working in**

> "Which Tidal Control environment am I connected to?"

Uses `currentTenant`. Worth asking first if you have access to more than one environment.

**Find the right person**

> "List our platform users and tell me which documents each of them owns."

Uses `userFind` and `personFind` to resolve names before you assign ownership. `currentUser` answers *"who am I signed in as?"*, and `groupFind` lists the groups people belong to.

## Tips for the best results

- **Be specific about scope.** Mention project names, asset identifiers, zones, or categories when you have them. The tools use these to filter accurately.
- **Chain operations naturally.** You don't need to call tools one by one; describe your goal and the assistant sequences the right tools.
- **Ask for the result back.** Adding "then show me the result" makes the assistant read the record after writing to it, which is how most clients catch a change that didn't land the way they meant.
- **If a tool seems missing, say so.** The server exposes more tools than most clients load at once. Telling the assistant what you're trying to do prompts it to look for the rest rather than give up.
- **Mutations ask for confirmation.** Your AI client may prompt before running a change (updating a score, creating a record, deleting something). This is expected.
- **Your permissions apply.** A read-only user can read through the MCP but can't create or change records, exactly as in the portal.
- **Approved policies are protected.** Editing the approved version of a policy is blocked over MCP; amend the draft in the portal's policy editor.
- **Some calls take a moment.** Semantic search, batch reads, and anything that reaches an external tracker are slower than a plain lookup.

## Tool reference

The server exposes considerably more tools than are listed here. These are the ones clients use regularly.

### Documents and policies

<table>
  <thead>
    <tr>
      <th>Tool</th>
      <th>Type</th>
      <th>What it does</th>
    </tr>
  </thead>
  <tbody>
    <tr><td><code>documentSearch</code></td><td>Read</td><td>Semantic search across document content</td></tr>
    <tr><td><code>documentFind</code></td><td>Read</td><td>List or locate documents by name or type</td></tr>
    <tr><td><code>documentGetContent</code></td><td>Read</td><td>Retrieve a document's full text</td></tr>
    <tr><td><code>documentGetContentBatch</code></td><td>Read</td><td>Retrieve several documents' text in one call</td></tr>
    <tr><td><code>requiredDocumentFind</code></td><td>Read</td><td>List the documents your adopted frameworks require</td></tr>
    <tr><td><code>documentCreate</code></td><td>Mutating</td><td>Create a new document</td></tr>
    <tr><td><code>documentEdit</code></td><td>Mutating</td><td>Apply a precise inline change to a document's text</td></tr>
    <tr><td><code>documentUpdate</code></td><td>Mutating</td><td>Replace a document's whole body</td></tr>
    <tr><td><code>documentClassificationFind</code></td><td>Read</td><td>See which document fulfils which policy, and its approval state</td></tr>
    <tr><td><code>documentClassificationCreate</code></td><td>Mutating</td><td>Record that a document fulfils a policy</td></tr>
    <tr><td><code>documentClassificationCreateDraft</code></td><td>Mutating</td><td>Derive an editable draft, leaving the approved version intact</td></tr>
    <tr><td><code>documentClassificationUpdate</code></td><td>Mutating</td><td>Approve or revoke a policy classification</td></tr>
    <tr><td><code>documentClassificationAssignOwner</code></td><td>Mutating</td><td>Assign a policy owner to a classification</td></tr>
  </tbody>
</table>

### Controls and frameworks

<table>
  <thead>
    <tr>
      <th>Tool</th>
      <th>Type</th>
      <th>What it does</th>
    </tr>
  </thead>
  <tbody>
    <tr><td><code>controlFind</code></td><td>Read</td><td>Search controls; filter by risk, framework, or category</td></tr>
    <tr><td><code>controlCount</code></td><td>Read</td><td>Count controls matching a filter</td></tr>
    <tr><td><code>frameworkFind</code></td><td>Read</td><td>List adopted frameworks and their state</td></tr>
    <tr><td><code>referenceFind</code></td><td>Read</td><td>List framework clause references, such as ISO 27001 Annex A</td></tr>
    <tr><td><code>referenceCount</code></td><td>Read</td><td>Count the clause references attached to a control</td></tr>
  </tbody>
</table>

### Risks

<table>
  <thead>
    <tr>
      <th>Tool</th>
      <th>Type</th>
      <th>What it does</th>
    </tr>
  </thead>
  <tbody>
    <tr><td><code>riskFind</code></td><td>Read</td><td>List risks; filter by residual level, treatment, or links</td></tr>
    <tr><td><code>riskCount</code></td><td>Read</td><td>Count risks matching a filter</td></tr>
    <tr><td><code>riskCreate</code></td><td>Mutating</td><td>Create a new risk</td></tr>
    <tr><td><code>riskUpdate</code></td><td>Mutating</td><td>Update a risk's name, description, or category</td></tr>
    <tr><td><code>riskAddControls</code></td><td>Mutating</td><td>Link mitigating controls to a risk</td></tr>
    <tr><td><code>riskAssessmentFind</code></td><td>Read</td><td>List a risk's assessments (its score history)</td></tr>
    <tr><td><code>riskAssessmentCreate</code></td><td>Mutating</td><td>Score a risk: impact, likelihood, residual, treatment</td></tr>
    <tr><td><code>riskAssessmentUpdate</code></td><td>Mutating</td><td>Revise an assessment's scores or treatment</td></tr>
  </tbody>
</table>

### Assets

<table>
  <thead>
    <tr>
      <th>Tool</th>
      <th>Type</th>
      <th>What it does</th>
    </tr>
  </thead>
  <tbody>
    <tr><td><code>assetFind</code></td><td>Read</td><td>List or locate assets in the register</td></tr>
    <tr><td><code>assetCount</code></td><td>Read</td><td>Count assets matching a filter</td></tr>
    <tr><td><code>assetCreate</code></td><td>Mutating</td><td>Add an asset to the register</td></tr>
    <tr><td><code>assetUpdate</code></td><td>Mutating</td><td>Update asset fields: CIA scores, RTO/RPO, category, dates</td></tr>
  </tbody>
</table>

### Vendors

<table>
  <thead>
    <tr>
      <th>Tool</th>
      <th>Type</th>
      <th>What it does</th>
    </tr>
  </thead>
  <tbody>
    <tr><td><code>vendorFind</code></td><td>Read</td><td>List or locate vendors</td></tr>
    <tr><td><code>vendorCount</code></td><td>Read</td><td>Count vendors matching a filter</td></tr>
    <tr><td><code>vendorCreate</code></td><td>Mutating</td><td>Add a new vendor</td></tr>
    <tr><td><code>vendorUpdate</code></td><td>Mutating</td><td>Update a vendor's details</td></tr>
    <tr><td><code>vendorAssessmentFind</code></td><td>Read</td><td>Read a vendor's current assessment</td></tr>
    <tr><td><code>vendorAssessmentCreate</code></td><td>Mutating</td><td>Assess a vendor: access, criticality, jurisdiction, rating</td></tr>
    <tr><td><code>vendorAssessmentUpdate</code></td><td>Mutating</td><td>Record or revise the values on an assessment</td></tr>
    <tr><td><code>evidenceFind</code></td><td>Read</td><td>List the evidence held against a vendor, control, or activity</td></tr>
  </tbody>
</table>

### Tasks and activities

<table>
  <thead>
    <tr>
      <th>Tool</th>
      <th>Type</th>
      <th>What it does</th>
    </tr>
  </thead>
  <tbody>
    <tr><td><code>activityFind</code></td><td>Read</td><td>List compliance tasks: issues, assessments, executions</td></tr>
    <tr><td><code>activityCount</code></td><td>Read</td><td>Count tasks matching a filter</td></tr>
    <tr><td><code>activityCreateIssue</code></td><td>Mutating</td><td>Create an issue (finding) task</td></tr>
    <tr><td><code>activityUpdateIssue</code></td><td>Mutating</td><td>Set an issue's owner, due date, or status</td></tr>
    <tr><td><code>activityCloseIssue</code></td><td>Mutating</td><td>Close a finding</td></tr>
    <tr><td><code>activityIssueAddControls</code></td><td>Mutating</td><td>Link an issue to the controls it concerns</td></tr>
    <tr><td><code>activityCreateExecution</code></td><td>Mutating</td><td>Schedule a control run</td></tr>
    <tr><td><code>activityUpdateExecution</code></td><td>Mutating</td><td>Change a run's due date, owner, or outcome</td></tr>
    <tr><td><code>activityExecutionAddControls</code></td><td>Mutating</td><td>Link a run to the controls it evidences</td></tr>
    <tr><td><code>activityCloseExecution</code></td><td>Mutating</td><td>Close a finished run</td></tr>
    <tr><td><code>planFind</code></td><td>Read</td><td>List the plans a control or activity belongs to</td></tr>
    <tr><td><code>commentFind</code></td><td>Read</td><td>Read the discussion on a record</td></tr>
    <tr><td><code>commentAdd</code></td><td>Mutating</td><td>Add a note to a record</td></tr>
    <tr><td><code>externalIssueCreate</code></td><td>Mutating</td><td>Push a finding to a connected tracker such as Jira or Linear</td></tr>
  </tbody>
</table>

### Tests and insights

<table>
  <thead>
    <tr>
      <th>Tool</th>
      <th>Type</th>
      <th>What it does</th>
    </tr>
  </thead>
  <tbody>
    <tr><td><code>testFind</code></td><td>Read</td><td>List automated tests and their pass/fail status</td></tr>
    <tr><td><code>testResultFind</code></td><td>Read</td><td>Historical pass/fail results for a test</td></tr>
    <tr><td><code>insightsFrameworkStatistics</code></td><td>Read</td><td>Compliance posture per framework</td></tr>
    <tr><td><code>insightsTestStatistics</code></td><td>Read</td><td>Aggregate pass/fail counts across automated tests</td></tr>
    <tr><td><code>insightsAssetsKpi</code></td><td>Read</td><td>Asset coverage: assigned, assessed, compliant</td></tr>
    <tr><td><code>insightsVendorsKpi</code></td><td>Read</td><td>Vendor coverage and assessment state</td></tr>
    <tr><td><code>insightsPersonnelKpi</code></td><td>Read</td><td>Personnel coverage: onboarding and document acceptance</td></tr>
    <tr><td><code>insightsActivityStatistics</code></td><td>Read</td><td>Open, overdue, and completed task counts</td></tr>
  </tbody>
</table>

### People and context

<table>
  <thead>
    <tr>
      <th>Tool</th>
      <th>Type</th>
      <th>What it does</th>
    </tr>
  </thead>
  <tbody>
    <tr><td><code>currentTenant</code></td><td>Read</td><td>Which Tidal Control environment the session is connected to</td></tr>
    <tr><td><code>currentUser</code></td><td>Read</td><td>Which account the session is signed in as</td></tr>
    <tr><td><code>userFind</code></td><td>Read</td><td>List platform users</td></tr>
    <tr><td><code>personFind</code></td><td>Read</td><td>List people in the personnel register</td></tr>
    <tr><td><code>groupFind</code></td><td>Read</td><td>List groups and their members</td></tr>
  </tbody>
</table>