Manifest and run

Fetch the manifest #

curl https://your-instance.example.com/mcp/manifest.json \
  -H "X-Auth: <AGENT_API_KEY>"

The response is a list of tools the caller may use. Each topology tool looks like this:

{
  "id": "topology:weather-report",
  "title": "weather-report",
  "description": "Returns tomorrow's weather report for a city.",
  "kind": "query",
  "input_schema": {
    "type": "object",
    "properties": { "city": { "type": "string" } },
    "required": ["city"]
  },
  "output_schema": { "type": "object" },
  "requires_confirmation": true,
  "llm_format": false
}

Field	Meaning
`id`	The tool id, always `topology:{name}`.
`description`	Natural-language selection signal for the LLM.
`kind`	`query` (returns data via a response node) or `command` (fire-and-forget).
`input_schema`	JSON-schema the arguments are validated against.
`output_schema`	Present when the manifest declares one.
`requires_confirmation`	Present and `true` when the run must be confirmed first.
`llm_format`	Present and `true` when the assistant may reformat the output.

Run a tool #

curl -X POST https://your-instance.example.com/mcp/run \
  -H "X-Auth: <AGENT_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "topology:weather-report",
    "args": { "city": "Brno" }
  }'

The tool accepts both the canonical topology:{name} id and a bare {name}, since LLMs frequently drop the prefix.

Argument validation #

Before the topology starts, Pulse coerces lossless scalar values to the declared types (for example "20" to an integer when the schema asks for one) and then hard-validates the arguments against input_schema. An invalid call is rejected and never reaches the topology. Never trust the model: the schema is the contract.

Run response #

{
  "topology": "weather-report",
  "kind": "query",
  "correlation_id": "6f1c...",
  "request_id": "",
  "started": true,
  "status": "pending"
}

`kind`	`status`	Meaning
`command`	`started` / `failed`	Fire-and-forget. The process was dispatched.
`query`	`pending`	The process is running; its payload arrives via the response node.

A tool that is not in the caller's manifest resolves to an unknown tool and is never run, even if the name is guessed exactly. The error does not reveal whether another group's topology exists.

Where to go next #

Async and the response node: receive a query result.
Caller identity: the identity header.