# MCP tools

Complete lookup reference for the tools and argument shapes served by ptah mcp.

Source: https://docs.ptah.run/v0.25.0/reference/mcp-tools/

The running server's `tools/list` response is authoritative for its
`agentapi.Version`. Use the index below to find a Ptah-owned tool, then use that
response for its machine-generated JSON Schema.

The server exposes tools only. It declares no MCP resources or prompts.

## The reading tools

| Tool | Purpose |
| --- | --- |
| `describe_session` | Report policy, configured scopes, targets, and version. |
| `validate_schema` | Validate a declared schema for one dialect. |
| `render_schema` | Render declared schema DDL in dependency order. |
| `schema_lineage` | Trace base columns feeding view columns. |
| `search_docs` | Search Ptah documentation and return document and heading evidence. |
| `read_database` | Introspect an operator-configured database target. |
| `inference_plan` | Plan an embedding-generation change and report outbound text. |
| `inference_status` | Report generation progress and cutover blockers. |

## The artifact tools

These tools appear only when the server has a workspace.

| Tool | Purpose | May write |
| --- | --- | --- |
| `read_artifact` | List an artifact directory or read one file with digests. | no |
| `preview_patch` | Validate and diff a proposed artifact patch. | no |
| `apply_patch` | Apply one preview, verify, and undo introduced failures. | yes, when policy permits |

Nothing on this surface applies a migration to a database.

## Session and schema tools

`describe_session` takes no arguments.

`validate_schema`, `render_schema`, and `schema_lineage` accept:

| Argument | Type | Requirement |
| --- | --- | --- |
| `dialect` | string | Required. One dialect accepted by the running server. |
| `source` | object | Required. `root_dirs` and `schema_files`; at least one entry across both. |

Schema paths resolve inside the configured schema source roots. Sources with a
scheme are refused.

`search_docs` accepts the query defined by the running tool schema and returns
the matching Ptah document and heading with its answer.

## Database and inference tools

`read_database` accepts:

| Argument | Type | Requirement |
| --- | --- | --- |
| `target` | string | A configured database name; omit only when exactly one exists. |
| `schemas` | array | Schemas to inspect; empty uses the connection default. |

There is no URL argument. The operator configures the connection when starting
the process, and for an engine an executable provider serves, the provider too.
No tool argument names a manifest, an engine or an executable. A call that adds
one is refused against the tool's input schema.

`inference_plan` and `inference_status` use the argument schemas advertised by
the running server. Their responses distinguish measured state, inferred state,
unsupported behavior, and text that would leave the database.

## Artifact tool arguments

`read_artifact` accepts:

| Argument | Type | Requirement |
| --- | --- | --- |
| `artifact` | string | Required: `migrations`, `schema`, or `tests`. |
| `path` | string | A file inside the configured directory; omit to list it. |

`preview_patch` accepts:

| Argument | Type | Requirement |
| --- | --- | --- |
| `artifact` | string | Required. |
| `changes` | array | Required file operations. Use the field names from `tools/list`. |
| `expected_digest` | string | The artifact digest this patch was composed against. Required for a later apply. |
| `summary` | string | The model's untrusted description shown in approval and audit output. |

Paths are relative to the artifact directory and use forward slashes.

`apply_patch` accepts:

| Argument | Type | Requirement |
| --- | --- | --- |
| `preview_token` | string | Required; returned by `preview_patch`. |
| `patch_id` | string | Required; must belong to the same preview. |

The token is single-use and expires after fifteen minutes. Apply compares the
artifact digest again, runs the configured gates, and either keeps the result or
restores the prior bytes.

## Warnings a call raises

A call reports the warnings its own work raised, such as names PostgreSQL cuts
to 63 bytes in the schema `validate_schema` read. Each call is reported on its
own: a second call that reads the same file reports the same warnings again.
The result carries them twice, after the answer, and neither changes the
response a tool documents:

- A text content item follows the answer, one `warning:` line per kind of
  warning. A model reads it with the answer.
- The result's `_meta` lists them under `ptah.run/warnings`, each with
  `category`, `count`, `message` and `objects`, the line of every object it
  counts. A client program reads them there.

```json
{
  "_meta": {
    "ptah.run/warnings": [
      {
        "category": "truncated-name",
        "count": 3,
        "message": "3 names are longer than 63 bytes; the server keeps their first 63 bytes, and they are read that way; the result's _meta lists them under ptah.run/warnings",
        "objects": [
          "schema file schema.sql: index \"axxx…_idx\" in schema \"public\" is 68 bytes; the server keeps its first 63: \"axxx…\"",
          "schema file schema.sql: index \"bxxx…_idx\" …",
          "schema file schema.sql: index \"cxxx…_idx\" …"
        ]
      }
    ]
  }
}
```

A call that raises no warning carries neither. The server writes nothing about
a call's warnings on its standard error; set `PTAH_LOG_LEVEL=debug` when
starting it to list the objects in its log as well.

## Operations deliberately absent

`schema inspect`, `schema diff`, and `migrations lint` need a scratch database
that Ptah resets destructively. They are not exposed behind read-only MCP names.
Run them through the native CLI, where the person starting the operation also
names the disposable database.

See [Configure agent permissions](../../operate/ai-agent-permissions/) for the
capability model and [Troubleshoot Ptah agent calls](../../operate/ai-agent-troubleshooting/)
for stable failure codes.