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

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

Types: Execute · Mcp

Output

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

      some_field:
        ref: MyTool

Properties

name

Tool display name

Required: Yes Type: String

---

type

Tool type hint (e.g. http, mcp, soat, 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 Nullable: Yes

---

mcp

MCP server connection configuration. Required for mcp tools.

Required: No Type: Mcp Nullable: Yes

---

actions

Allowlist of actions the tool exposes. For soat 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

---

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

---

discussion_id

For discussion tools: the ID of the discussion to invoke.

Required: No Type: String Nullable: Yes

---

output_mapping

Universal JSON Logic mapping applied to the tool's raw result, for every tool type. Evaluated over &#123; output: <raw result> &#125;, 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

---

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

---