Tool

@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.
• output (object, required): JSON Schema for the tool output. MUST validate under Draft 2020-12.
• needs (array of 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): 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.
• limits (object): Sandbox-enforced resource caps at dispatch. Optional additive field.
  • memMB (integer, required)
  • cpuMs (integer, required)
• network (object or object): Network egress policy. Optional additive field. Discriminated on kind.
• 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 (object or object): 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.
• spec (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

Type: object or object

HttpRequestBodySpec

Type: object or object or object

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)
• authorization (HttpAuthSpec)
• requestBody (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)