---
title: "MCP Tools Reference"
slug: "mcp-tools-reference"
updated: 2026-06-25T22:13:25Z
published: 2026-06-25T22:13:25Z
canonical: "docs.validatar.com/mcp-tools-reference"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.validatar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Tools Reference

This reference documents all tools available through the Validatar MCP Server. Tools are organized into read-only operations (browsing and querying) and write operations (creating, updating, and executing).

---

## Read-Only Tools

These tools retrieve information from your Validatar instance without making changes.

---

### describe

Retrieve detailed information about a Validatar object.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `object_type` | enum | Yes | The type of object to describe (DataSource, Schema, Table, Column, Project, Folder, Test, Job) |
| `object_id` | integer | Yes | The ID of the object |
| `output_sections` | list | No | Specific sections to include in the response (limits output for large objects) |
| `window` | string | No | Time window for time-sensitive data (e.g., recent job results) |

**Use when:** You want to inspect the configuration, status, or metadata of a specific object in your catalog or project.

---

### describe_quick_test

Get the details of a specific quick test available for a table or column.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `object_type` | enum | Yes | Table or Column |
| `object_id` | integer | Yes | The ID of the table or column |
| `template_test_id` | integer | Yes | The ID of the quick test template to describe |

**Use when:** You want to understand what a specific quick test does before creating it, including its variables and configuration options.

---

### list

List child objects of a parent Validatar object.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `object_type` | enum | Yes | The type of the parent object |
| `object_id` | integer | Yes | The ID of the parent object |
| `child_type` | enum | Yes | The type of child objects to list |
| `filters` | object | No | Filter criteria to narrow results |
| `page_size` | integer | No | Number of results per page |
| `page_index` | integer | No | Page number for pagination |

**Use when:** You want to browse the hierarchy — for example, listing schemas in a data source, tables in a schema, columns in a table, tests in a folder, or projects on the home page.

---

### list_quick_tests

List available quick tests for a table or column.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `object_type` | enum | Yes | Table or Column |
| `object_id` | integer | Yes | The ID of the table or column |
| `filter_by_quality_dimension` | string | No | Filter by quality dimension (e.g., Completeness, Uniqueness) |
| `filter_by_test_status` | string | No | Filter by whether a test already exists |
| `filter_by_search_text` | string | No | Free-text search filter |

**Use when:** You want to see what out-of-the-box tests are available for a specific table or column, optionally filtered by quality dimension or existing test coverage.

---

### list_custom_metadata_options

List custom metadata fields and their options for a Validatar object.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `object_type` | enum | Yes | The type of object |
| `object_id` | integer | Yes | The ID of the object |
| `only_return_populated` | boolean | Yes | Only return fields that have values set |
| `only_return_visible` | boolean | Yes | Only return fields visible in the UI |
| `type_equals_filter` | string | No | Filter by field type |
| `name_contains_filter` | string | No | Filter by field name |
| `reference_key_contains_filter` | string | No | Filter by reference key |

**Use when:** You want to see what custom metadata fields are available for an object and what values they currently hold.

---

### convert_url_to_key

Convert a Validatar application URL to an object type and ID.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | Yes | A Validatar application URL |

**Use when:** You have a URL from the Validatar UI and need to determine the object type and ID for use with other MCP tools.

---

### get_global_trust_score_settings

Retrieve the global trust score configuration.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `output_sections` | list | No | Sections to include: QualityDimensions, SeverityLevels, ImpactRatings |

**Use when:** You need to understand how trust scores are calculated, what quality dimensions are configured, or what severity levels and impact ratings are available.

---

### search_documentation_articles

Search across all articles in the Validatar documentation.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `search_query` | string | Yes | The search terms to look for |

**Use when:** You want to find relevant documentation articles by keyword or topic.

---

### search_documentation_assistive

Ask the Validatar documentation assistant a question.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `prompt` | string | Yes | A natural language question about Validatar |

**Use when:** You have a question about how Validatar works and want a synthesized answer drawn from the documentation.

---

## Write Tools

These tools create, modify, or execute operations in your Validatar instance. All write operations are tracked as AI Actions and can be reverted.

---

### create_standard_test

Create a new standard test in a project.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `project_id` | integer | Yes | The project to create the test in |
| `config` | object | Yes | Standard test configuration (includes name, folder, data sets, success conditions, and test parameters) |

**Use when:** You want to create a one-off test that validates a specific data condition with explicitly defined source and target queries.

---

### create_template_test

Create a new template test in a project.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `project_id` | integer | Yes | The project to create the test in |
| `config` | object | Yes | Template test configuration (includes name, folder, metadata selection criteria, variables, and test logic) |

**Use when:** You want to create a reusable test definition that automatically generates child tests based on metadata selection criteria.

---

### create_quick_test

Create a quick test for a table or column from an available template.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `object_type` | enum | Yes | Table or Column |
| `object_id` | integer | Yes | The ID of the table or column |
| `template_test_id` | integer | Yes | The ID of the quick test template to use |
| `variables` | object | Yes | Variable values required by the template |
| `custom_fields` | object | Yes | Custom field values to assign to the created test |

**Use when:** You want to quickly add test coverage to a table or column using one of the predefined quick test templates.

---

### create_data_source

Create a new data source.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | object | Yes | Data source configuration (includes name, connection details, template, and settings) |

**Use when:** You want to register a new database connection in Validatar for testing and profiling.

---

### update_data_source

Update an existing data source configuration.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `data_source_id` | integer | Yes | The ID of the data source to update |
| `config` | object | Yes | Updated data source configuration |

**Use when:** You need to modify connection details, settings, or other properties of an existing data source.

---

### execute_standard_tests

Execute one or more standard tests.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `object_id_list` | list of integers | Yes | List of standard test IDs to execute (not template test IDs) |

**Use when:** You want to run specific tests and see their results. Only standard tests (including child tests materialized from templates) can be executed directly.

---

### execute_data_source_script

Execute a SQL or Python script against a data source.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `data_source_id` | integer | Yes | The data source to execute against |
| `script` | string | Yes | The SQL or Python script to run |
| `timeout_seconds` | integer | No | Maximum execution time (default applies if omitted) |
| `max_rows` | integer | No | Maximum number of rows to return |

**Use when:** You want to run ad-hoc queries to explore data, validate assumptions, or troubleshoot test results.

---

### update_custom_metadata

Update custom metadata field values for a Validatar object.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `object_type` | enum | Yes | The type of object to update |
| `object_id` | integer | Yes | The ID of the object |
| `field_values` | object | Yes | Field values to set, structured as `{"field_name": {"values": ["value1", "value2"]}}` |

**Use when:** You want to tag or classify objects with custom metadata — for example, assigning data domains, owners, or sensitivity levels.

---

### create_folder

Create a new folder in a project.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `project_id` | integer | Yes | The project to create the folder in |
| `parent_folder_id` | integer | Yes | The parent folder ID |
| `name` | string | Yes | Name for the new folder |

**Use when:** You want to organize tests into a folder structure within a project.

---

### rename_folder

Rename an existing folder.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `project_id` | integer | Yes | The project containing the folder |
| `folder_id` | integer | Yes | The folder to rename |
| `name` | string | Yes | The new folder name |

**Use when:** You want to update a folder's display name.

---

### move_folder

Move a folder to a different parent.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `project_id` | integer | Yes | The project containing the folder |
| `folder_id` | integer | Yes | The folder to move |
| `parent_folder_id` | integer | Yes | The new parent folder ID |

**Use when:** You want to reorganize the folder hierarchy within a project.

---

### delete_folder

Delete a folder from a project.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `project_id` | integer | Yes | The project containing the folder |
| `folder_id` | integer | Yes | The folder to delete |
| `delete_child_tests` | boolean | Yes | Whether to also delete tests inside the folder |

**Use when:** You want to remove an unused folder. Set `delete_child_tests` to `true` to remove contained tests, or `false` to move them to the parent folder.

---

### create_project

Create a new project.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | object | Yes | Project configuration (includes name and settings) |

**Use when:** You want to set up a new project for organizing and executing tests.

---

### update_project

Update an existing project's configuration.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | object | Yes | Updated project configuration |

**Use when:** You need to modify project settings or properties.

---

### revert_action

Revert a change made by a previously executed AI Action.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `action_key` | string | Yes | The revert action key returned by the original write operation |
| `comment` | string | Yes | A comment explaining why the action is being reverted |
| `reason` | enum | Yes | Reason for reverting: AiDidNotDoWhatWasRequested, ChangeNoLongerDesired, Testing, or Other |

**Use when:** An AI-initiated change needs to be undone — for example, a test was created incorrectly or a metadata update needs to be rolled back.

---

## Object Types

The following object types are used across tools that accept an `object_type` parameter:

| Object Type | Description |
| --- | --- |
| Home | The top-level entry point |
| Catalog | The data catalog |
| DataSource | A configured database connection |
| Schema | A schema within a data source |
| Table | A table within a schema |
| Column | A column within a table |
| Project | A test project |
| Folder | A folder within a project |
| Test | A standard or template test |
| Job | A test execution job |
| Report | A report definition |
| GlobalSettings | Instance-wide settings |
| Marketplace | The Validatar marketplace |

---

## Custom Field Value Format

Several tools accept or return custom field values. The format is consistent:

```
{
  "field_name": {
    "values": ["value1", "value2"]
  },
  "another_field": {
    "values": ["single_value"]
  }
}
```

Each field accepts a list of values — even single-value fields use an array.

---

## Related

- [Connecting to the Validatar MCP Server](/docs/connecting-to-the-validatar-mcp-server) — setup and authentication
- [Using the Validatar AI Chat Interface](/getting-started/how-to/using-the-validatar-ai-chat-interface) — the in-app AI chat experience