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.

{
  "_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 for the capability model and Troubleshoot Ptah agent calls for stable failure codes.