# Tool

> A tool definition.

`@kindgi/specs/tool.schema.json`, schema version 1.1.0.

A tool definition. Authored once; the runtime picks transport (native in-process for tools built into the runtime, MCP over the wire for cross-process / cross-org / third-party tools). Every tool declares its typed I/O, its context needs (typed DI), and its side-effects — enabling policy enforcement and parallel scheduling by the kernel.

- `id` (string, required): Unique tool identifier. Convention: '\<pack>.\<tool>' (e.g. 'acme.verify-citation') or a bare id for tools built into Kindgi.

- `description` (string, required): Human- and LLM-readable description of what this tool does. Load-bearing: this is what the LLM sees when deciding to call the tool.

- `version` (string, required)

- `input` (object, required): JSON Schema for the tool input. MUST validate under Draft 2020-12, except on an MCP server's tool (`transport: "mcp"`), whose schemas are in the dialect their `$schema` declares: draft-06, draft-07, 2019-09 or 2020-12.

- `output` (object, required): JSON Schema for the tool output. MUST validate under Draft 2020-12, except on an MCP server's tool (`transport: "mcp"`), whose schemas are in the dialect their `$schema` declares: draft-06, draft-07, 2019-09 or 2020-12.

- `needs` (array of [Need](https://docs.kindgi.com/v0.1.9/reference/schemas/tool.md#need)): Typed context requirements — named slots (e.g. `tenant`, `run`, `blob`, `memory:facts`) the runtime injects via `ToolContext`. Declarative: not checked when a flow is loaded. `needsSpec` is the typed, discriminated form.

- `effects` (array of [Effect](https://docs.kindgi.com/v0.1.9/reference/schemas/tool.md#effect)): Declared side-effects. Enables policy enforcement (can this tool run in this tenant?), safe parallelization (are two calls conflicting?), and causal provenance.

- `transport` (`"auto"` | `"native"` | `"mcp"`): Transport hint. 'auto' (default) lets the runtime pick native when possible, MCP otherwise. 'native' requires in-process execution. 'mcp' requires MCP execution. Deployment-time concern; authoring is unchanged.

- `mcpEndpoint` (string): If transport = 'mcp' (or resolved to MCP by 'auto'), the MCP endpoint URI. Format: 'mcp+stdio://\<command>', 'mcp+http\://\<url>', 'mcp+sse://\<url>'.

- `metadata` (map of any): Free-form annotations (author, docs URL, tags). Not interpreted by the kernel.

- `sandbox` (`"none"` | `"context-isolated"` | `"strict"`): Isolation posture the runtime enforces around the handler. Optional additive field.

- `mutating` (boolean): Semantic marker: `true` when this tool causes observable side effects (writes state, calls external APIs with mutations, sends messages). Read-only tools set `false`. Absent defaults to `true`. Consumed by the HITL default classifier — a read-only tool passes straight through, a mutating tool asks on first use.

- `needsApprovalWhenUnattended` (boolean): `true` when a person must say yes to every call of this tool in a run no person started (a schedule, a webhook, an event or a service account's key started it). In such a run an agent's call waits for a person's yes whatever the agent's approval rules say, and a flow's tool step that calls it is refused. Absent means `false`. Optional additive field.

- `limits` (object): Sandbox-enforced resource caps at dispatch. Optional additive field.

  - `memMB` (integer, required)
  - `cpuMs` (integer, required)

- `network` (one of the objects below): Network egress policy. Optional additive field. Discriminated on `kind`.

  - an object
    - `kind` (`"none"` | `"unrestricted"`, required)

  - an object

    - `kind` (`"allowlist"`, required)
    - `hosts` (array of string, required)

- `needsSpec` (object): Typed discriminated needs (env / secrets / config / capabilities / bindings). Optional additive field.

  - `env` (map of object)
  - `secrets` (map of object)
  - `config` (map of object)
  - `capabilities` (array of string)
  - `bindings` (array of string)

- `codeArtifactRef` (one of the objects below): Handler-artifact pointer. Discriminated on `kind`: `oci` is the deploy-pipeline shape (image + module path + artifactVersion); `filesystem` is the local-development shape — absolute host path at the pack's on-disk handler file. Production servers SHOULD reject `filesystem`.

  - an object

    - `kind` (`"oci"`, required)
    - `imageRef` (string, required)
    - `modulePath` (string, required)
    - `artifactVersion` (string, required)

  - an object

    - `kind` (`"filesystem"`, required)
    - `modulePath` (string, required)

- `spec` ([HttpToolSpec](https://docs.kindgi.com/v0.1.9/reference/schemas/tool.md#httptoolspec)): Declarative handler spec. Discriminated on `kind`; the framework's synthesizer registry maps kind → runtime handler. Mutually exclusive with an imperative handler at author time.

## Definitions

### Need

- `name` (string, required): The named context slot (e.g. 'tenant', 'db', 'run', 'provenance', 'memory:facts', 'blob').
- `optional` (boolean)

### Effect

- `kind` (`"reads"` | `"writes"` | `"deletes"` | `"network"` | `"spawns-run"` | `"emits-event"` | `"external-side-effect"` | `"sensitive-data-egress"`, required)
- `resource` (string): Resource identifier (e.g. 'memory:facts', 'blob:\*', 'external:api.example.com'). Used by the policy engine to authorize the effect.
- `notes` (string)

### ToolSecretRef

- `envName` (string, required)
- `name` (string, required)

### HttpHeaderSpec

- `name` (string, required)
- `value` (string, required)

### HttpAuthSpec

One of:

- an object

  - `kind` (`"bearer"`, required)
  - `secretRef` ([ToolSecretRef](https://docs.kindgi.com/v0.1.9/reference/schemas/tool.md#toolsecretref), required)

- an object

  - `kind` (`"header"`, required)
  - `headerName` (string, required)
  - `secretRef` ([ToolSecretRef](https://docs.kindgi.com/v0.1.9/reference/schemas/tool.md#toolsecretref), required)

### HttpRequestBodySpec

One of:

- an object
  - `kind` (`"json-input"`, required)

- an object
  - `kind` (`"input-passthrough"`, required)

- an object

  - `kind` (`"text"`, required)
  - `template` (string, required)

### HttpToolSpec

Declarative HTTP-invocation spec. Attached to `ToolManifest.spec` under the discriminant `kind: 'http'`. The runtime `Tool.handler` is synthesized by the 'http' spec synthesizer to perform URL-template substitution, secret-ref resolution via `ToolContext.resolveSecret`, and the outbound fetch. All fields serialize cleanly to JSON.

- `kind` (`"http"`, required)

- `method` (`"GET"` | `"POST"` | `"PUT"` | `"PATCH"` | `"DELETE"`, required)

- `urlTemplate` (string, required): URL template with `{param}` placeholders substituted from the tool's input at invoke time.

- `headers` (array of [HttpHeaderSpec](https://docs.kindgi.com/v0.1.9/reference/schemas/tool.md#httpheaderspec))

- `authorization` ([HttpAuthSpec](https://docs.kindgi.com/v0.1.9/reference/schemas/tool.md#httpauthspec))

- `requestBody` ([HttpRequestBodySpec](https://docs.kindgi.com/v0.1.9/reference/schemas/tool.md#httprequestbodyspec))

- `timeoutMs` (integer): Wall-clock timeout in ms. Default 30000.

- `parseJson` (boolean): When true (default), the response body is parsed as JSON before returning to the invoker.

- `successStatus` (object)

  - `min` (integer, required)
  - `max` (integer, required)