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

# Tool RPC contract

> Use the installed one-shot JSON process interface without MCP.

`kast-tool-rpc-complete` is a one-shot process interface. Run it from the
Kotlin Gradle repository or worktree. Each invocation writes one JSON object
to stdout.

## Discover

```shell theme={null}
"${XDG_DATA_HOME:-$HOME/.local/share}/kast/current/bin/kast-tool-rpc-complete" catalog
```

The reply has `type: "catalog"`, `catalog.schemaVersion: 2`, and
`catalog.tools[]`. Each tool has `name`, `description`, `inputSchema`,
and `effect` (`READ` or `WRITE`). Re-read it after an upgrade.

## Call

The command takes the tool name after `call` and one JSON object on stdin.
For a workspace-independent check:

```shell theme={null}
printf '%s\n' '{}' |
  "${XDG_DATA_HOME:-$HOME/.local/share}/kast/current/bin/kast-tool-rpc-complete" call health_check
```

Replace `health_check` and stdin with the [query example](/search) to
get compiler-backed symbols. Tool RPC exposes the same direct tool names as
[MCP](/reference/mcp-catalog), including `add_declaration`. It does not expose
`workspace_lifecycle`.

## Decode

The generated [reply union](/reference/models/tool-rpc-reply) is the process
contract:

| `type`              | Required field | Meaning                          |
| ------------------- | -------------- | -------------------------------- |
| `catalog`           | `catalog`      | Tool inventory and input schemas |
| `complete`          | `document`     | Completed canonical operation    |
| `qualified`         | `document`     | Known facts with a qualification |
| `rejected_document` | `document`     | Semantic or hosted rejection     |
| `rejected`          | `failure`      | Finite process boundary failure  |

Decode `document` using the selected tool's generated response schema.
Unknown `type` or `failure` values are incompatible with this contract.
An empty qualified query does not prove absence.

Copilot CLI and Pi can use the installed adapters described in
[the repository integration guide](https://github.com/amichne/kast/blob/main/docs/tool-rpc.md).