# Tool

> > This page is auto-generated from the formations OpenAPI spec.
> Do not edit manually — run `pnpm generate-formations-resource-docs` to regenerate.

# Tool

> This page is auto-generated from the formations OpenAPI spec.
> Do not edit manually — run `pnpm generate-formations-resource-docs` to regenerate.

Defines a tool (HTTP endpoint, MCP server, SOAT action, or pipeline) that agents can invoke during a generation.

## Syntax

```yaml
type: tool
properties:
  name: String
  type: String
  description: String
  parameters: Object
  execute: Execute
  mcp: Mcp
  actions: String[]
  denied_actions: String[]
  context_keys: String[]
  preset_parameters: Object
  pipeline: Object
  output_mapping: Object
  guardrail_ids: String[]
```

_Types: [Execute](#execute) · [Mcp](#mcp)_

## Output

The physical resource ID is the **public ID** of the created resource. Reference it from other resources with a `ref` expression:

```yaml
      some_field:
        ref: MyTool
```

## Properties

**`name`**

Tool display name

_Required_: Yes
_Type_: String

---

**`type`**

Tool type hint (e.g. http, mcp, builtin, pipeline)

_Required_: No
_Type_: String
_Nullable_: Yes

---

**`description`**

Tool description shown to the model

_Required_: No
_Type_: String
_Nullable_: Yes

---

**`parameters`**

JSON Schema describing the tool's input parameters (free-form, user-defined)

_Required_: No
_Type_: Object
_Nullable_: Yes

---

**`execute`**

HTTP execution configuration. Required for `http` tools.

_Required_: No
_Type_: [Execute](#execute)
_Nullable_: Yes

---

**`mcp`**

MCP server connection configuration. Required for `mcp` tools.

_Required_: No
_Type_: [Mcp](#mcp)
_Nullable_: Yes

---

**`actions`**

Allowlist of actions the tool exposes. For `builtin` tools: SOAT platform action names. For `mcp` tools: an optional allowlist of MCP tool names to scope the server surface (`null` exposes every tool).

_Required_: No
_Type_: Array of String
_Nullable_: Yes

---

**`denied_actions`**

For `mcp` tools: an optional denylist of MCP tool names to hide. Applied after `actions` and taking precedence over it — the ergonomic way to scope a read+write MCP server read-only by denying just the write tools. `null` denies nothing.

_Required_: No
_Type_: Array of String
_Nullable_: Yes

---

**`context_keys`**

Optional allowlist of `tool_context` keys forwarded to this tool as prefixed context headers. `null` or omitted forwards every key; `[]` forwards none. The server-pinned identity keys (`session_id`, `actor_id`, `actor_external_id`) are always forwarded, and a key consumed by a `{{context:<key>}}` token in this tool's own headers is substituted regardless of this list.

_Required_: No
_Type_: Array of String
_Nullable_: Yes

---

**`preset_parameters`**

Pre-filled parameter values injected at execution time

_Required_: No
_Type_: Object
_Nullable_: Yes

---

**`pipeline`**

Pipeline definition for `pipeline` tools: an ordered `steps` array, each invoking another tool by `tool_id` (optional `action`) with an `input` built from earlier results via JSON Logic over `{ input, steps }`, plus an optional `output` mapping. Step `input` keys and `var` paths use camelCase (the runtime form). Free-form, user-defined.

_Required_: No
_Type_: Object
_Nullable_: Yes

---

**`output_mapping`**

Universal JSON Logic mapping applied to the tool's raw result, for every tool type. Evaluated over `{ output: <raw result> }`, e.g. `{ "var": "output.text" }`. For `pipeline` tools this runs after the pipeline's own `output` mapping.

_Required_: No
_Type_: Object
_Nullable_: Yes

---

**`guardrail_ids`**

Guardrails attached at the tool scope.

_Required_: No
_Type_: Array of String
_Nullable_: Yes

---

## Sub-types

### Execute

Properties of the `execute` object.

**`url`**

Endpoint URL. Supports `{param}` placeholders resolved from tool arguments.

_Required_: No
_Type_: String

---

**`method`**

HTTP method (default: `POST`)

_Required_: No
_Type_: String
_Nullable_: Yes

---

**`headers`**

Static headers included in every request

_Required_: No
_Type_: Object
_Nullable_: Yes

---

**`body_mode`**

Request body encoding for `POST`/`PUT`/`PATCH`: `json` (default) or `multipart`. Incompatible with `auth.type: aws_sigv4`.

_Required_: No
_Type_: String
_Nullable_: Yes

---

**`auth`**

Computed request credential. `type` is `aws_sigv4` (with `region`, `service`, `access_key_id`, `secret_access_key` and optional `session_token`) or `gcp_service_account` (with `credentials` and `scopes`). Credential fields accept `{{secret:...}}` references.

_Required_: No
_Type_: Object
_Nullable_: Yes

---

### Mcp

Properties of the `mcp` object.

**`url`**

MCP server URL

_Required_: No
_Type_: String

---

**`headers`**

Headers included in every MCP request

_Required_: No
_Type_: Object
_Nullable_: Yes

---