# Workflows tools

CARTO Workflows lets your team package data preparation and analytical pipelines as **MCP Tools** that any agent connected to the MCP Server can call. Workflows tools complement the built-in [platform](/carto-for-agents/mcp-server/tools-reference/platform-tools.md) and [interactive](/carto-for-agents/mcp-server/tools-reference/interactive-tools.md) tools by exposing organization-specific logic (site selection, trade-area analysis, demand modeling, anything your team has built) in a form an agent can use.

Workflows tools come in two execution modes:

* **Sync**. The tool returns results immediately. Best for lightweight, fast queries.
* **Async**. The tool kicks off a job and returns a `jobId`. The agent then polls [`async_workflow_job_get_status_v1_0_0`](#async_workflow_job_get_status_v1_0_0) until the job is done, and retrieves the output with [`async_workflow_job_get_results_v1_0_0`](#async_workflow_job_get_results_v1_0_0). Best for long-running pipelines.

## Publish your own workflow as an MCP tool

Any workflow your organization builds in CARTO Workflows can be exposed as an MCP tool by adding the descriptions, inputs, and outputs that the MCP specification expects. For step-by-step guidance, see the [**Workflows as MCP Tools**](/carto-user-manual/workflows/workflows-as-mcp-tools.md) documentation in the CARTO User Manual.

### Best practices

To ensure reliable performance and accurate results when exposing Workflows as MCP Tools, consider the following guidelines:

* **Keep tool descriptions clear and specific.** Write concise descriptions that explain what the tool does and when it should be used. This helps the agent choose the right tool.
* **Define inputs precisely.** Use descriptive names and types for all parameters. Avoid ambiguous labels that could confuse the agent.
* **Test workflows thoroughly.** Run workflows manually before exposing them to confirm that the outputs match expectations.
* **Choose the right output mode.** Use **Sync** for lightweight, fast queries; use **Async** for long-running processes.
* **Version and update carefully.** When making changes to workflows, sync updates promptly and communicate changes to relevant users of the MCP Server.
* **Monitor usage and errors.** Track how tools are used and review errors to refine workflows or adjust descriptions as needed.

{% hint style="info" %}
With **Async** mode, the agent must poll for status and make an additional call to retrieve results when the job completes. Implementing this control flow in your agent's prompt may require additional work.
{% endhint %}

***

## Async job tools

The two tools below are how the agent drives an async workflow once it has been launched. They are built in to every MCP Server. You don't need to configure them.

### `async_workflow_job_get_status_v1_0_0`

**Description**

Gets the status of an async workflow job. Use this after calling an async workflow tool that returns a job ID. Poll this tool until the job status is `success` or `failure`.

**Input properties**

| Parameter        | Type   | Required | Description                                                                        |
| ---------------- | ------ | -------- | ---------------------------------------------------------------------------------- |
| `jobId`          | string | Yes      | The ID of the async workflow job (returned by the workflow tool that launched it). |
| `connectionName` | string | Yes      | The name of the connection used by the workflow.                                   |

**Output**

A JSON object containing the job status and metadata. Possible `status` values: `pending`, `running`, `success`, `failure`, `cancelled`.

<details>

<summary>Response example</summary>

```
{
  "status": 200,
  "data": {
    "jobId": "abc-123",
    "connectionName": "carto_dw",
    "providerId": "bigquery",
    "status": "running",
    "error": null,
    "createdAt": "2024-06-20T14:30:00.000Z"
  }
}
```

</details>

**Example**

After launching an async workflow that returned `jobId: "abc-123"`:

```
async_workflow_job_get_status_v1_0_0({
  jobId: "abc-123",
  connectionName: "carto_dw"
})
```

***

### `async_workflow_job_get_results_v1_0_0`

**Description**

Retrieves the results of an async workflow job after it has completed with `success` status. Call this only after [`async_workflow_job_get_status_v1_0_0`](#async_workflow_job_get_status_v1_0_0) confirms the job is done.

**Input properties**

| Parameter                 | Type   | Required | Description                                                                                                   |
| ------------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------- |
| `jobId`                   | string | Yes      | The ID of the async workflow job.                                                                             |
| `providerId`              | string | Yes      | The data warehouse provider. One of: `bigquery`, `snowflake`, `databricks`, `postgres`, `redshift`, `oracle`. |
| `connectionName`          | string | Yes      | The name of the connection used by the workflow.                                                              |
| `workflowOutputTableName` | string | Yes      | The fully qualified name of the workflow output table.                                                        |

**Output**

A JSON object containing the query results from the workflow output table. The `rows` array contains the actual data, and `schema` describes the column types.

<details>

<summary>Response structure</summary>

```
{
  "status": 200,
  "data": {
    "rows": [
      {
        "store_id": 1,
        "name": "Madrid Centro",
        "trade_area_geom": "POLYGON((-3.71 40.41, ...))",
        "drive_time_min": 10
      },
      {
        "store_id": 2,
        "name": "Madrid Norte",
        "trade_area_geom": "POLYGON((-3.69 40.48, ...))",
        "drive_time_min": 10
      }
    ],
    "schema": [
      { "name": "store_id", "type": "INT64" },
      { "name": "name", "type": "STRING" },
      { "name": "trade_area_geom", "type": "GEOGRAPHY" },
      { "name": "drive_time_min", "type": "INT64" }
    ]
  }
}
```

</details>

**Example**

After confirming the job completed successfully:

```
async_workflow_job_get_results_v1_0_0({
  jobId: "abc-123",
  providerId: "bigquery",
  connectionName: "carto_dw",
  workflowOutputTableName: "my_project.results.trade_areas"
})
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.carto.com/carto-for-agents/mcp-server/tools-reference/workflow-tools.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.