Skip to content
Kindgi

Fetch a tool manifest (latest active version)

View as Markdown
GET
/v1/tools/{toolId}
curl --request GET \
  --url https://example.com/v1/tools/example \
  --header 'Authorization: Bearer <token>'

Returns the latest active version of the tool. When all versions are unregistered (retired), the head row still exists but has no active version — the response is 410 tool-gone with the id, distinct from 404 tool-not-found (never registered). An item more than one project serves (an environment order carries it to later environments) answers its newest active version that can run in a project the caller reads, and 404 when there is none. projectId narrows that to one project. An item with one project answers its latest active version.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
toolId
required
string

ToolId — dotted namespace (acme.lookup-order).

Query Parameters

Section titled “Query Parameters”
projectId
string format: uuid

The newest active version that can run in this project, a project the caller reads; 404 when there’s none, or when the caller doesn’t read the project. An item with one project answers its latest version for its own project and 404 for any other; one that names no project (under kindgi dev, a pack’s agents, flows and tools) answers it for any. With authorization off, the caller reads every project. An older runtime ignores it and answers the latest version.

Responses

Section titled “Responses”

200

Section titled “200”

Tool manifest.

Media typeapplication/json
object
id
required

ToolId — dotted namespace (e.g. acme.verify-citation).

string
>= 1 characters
projectId

The tool’s project: every version of a tool is in the one project. Absent when the runtime doesn’t record it: a pack kindgi dev serves from disk, or a runtime before Kindgi 0.1.6.

string format: uuid
description
required
string
>= 1 characters
version
string
/^\d+\.\d+\.\d+$/
input
required

JSON Schema (Draft 2020-12) for the tool input.

object
key
additional properties
any
output
required

JSON Schema (Draft 2020-12) for the tool output.

object
key
additional properties
any
needs
Array<object>
object
name
required
string
>= 1 characters
optional
boolean
effects
Array<object>
object
kind
required
string
Allowed values: reads writes deletes network spawns-run emits-event external-side-effect sensitive-data-egress
resource
string
notes
string
transport
string
Allowed values: auto native mcp
mcpEndpoint
string
metadata
object
key
additional properties
any
mutating

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. It also decides what runs together: calls to read-only tools that a model step asks for one after another run at the same time, up to 8 at once, unless the agent sets parallelToolCalls: false; a call to a mutating tool runs on its own, and so does a call to a read-only tool that pauses or declares connections, since it may wait.

boolean
needsApprovalWhenUnattended

true: in a run no person started (one whose startedBy isn’t person), every call of this tool waits for a person’s yes, whatever the agent’s approval rules say, and a flow’s tool step that calls it is refused. A webhook trigger, a schedule or a mail trigger whose toolsAllowedUnattended names the tool (a project admin’s to set) lifts that, in its own runs only. A tool that uses a person’s connection, reads included, counts as declaring it. In a run a mail started, so does a tool that isn’t mutating: false, and one that uses the run’s own mailbox. Absent means false.

boolean
pauses

true when the tool may make its run wait for another system’s answer: each call gets a wait token, hands its link to that system, and answers pause; the system’s answer, valid against output, becomes the call’s result. The run waits at most 24 days (24 hours by default) and fails the call when the time passes. Only a pack tool with a handler can pause: not one with a declarative spec, nor an MCP tool. Absent means false.

boolean
storesFiles

true when the tool may store files for its run, such as a mail’s attachments: each call can store up to 10, the runtime checks each one’s bytes, and the tool returns the stored files in its result’s top-level files, which an agent is shown. Only a pack tool with a handler can store files: not one with a declarative spec, nor an MCP tool. Absent means false.

boolean
readsFiles

true when the tool may read stored files’ bytes, such as a PDF an agent was given, to parse it: each call can read a file its run may be shown, by its file value’s artifactId, as it was stored. Only a pack tool with a handler can read files: not one with a declarative spec, nor an MCP tool. Absent means false.

boolean
resultIsOutsideData

true when the tool’s results are text from outside that nobody checked, such as a mail someone sent: an agent reads each result as data, not instructions, in that turn and in every later turn’s history. Absent means false.

boolean
sandbox

Isolation posture the runtime enforces around the handler. Optional additive field.

string
Allowed values: none context-isolated strict
limits

Sandbox-enforced resource caps at dispatch. Optional additive field.

object
memMB
required
integer
>= 1
cpuMs
required
integer
>= 1
network
One of:

Network egress policy. Optional additive field. Discriminated on kind.

object
kind
required
string
Allowed values: none unrestricted
needsSpec

Typed discriminated needs (env / secrets / config / capabilities / bindings / connections). Optional additive field.

object
env
object
key
additional properties
object
secrets
object
key
additional properties
object
config
object
key
additional properties
object
capabilities
Array<string>
bindings
Array<string>
connections

Accounts at other apps the tool acts with, by the tool’s own name for each (mail). The runtime resolves them per call into the context’s connections.

object
key
additional properties
object
app
required

The app’s entry id: google, github.

string
/^[a-z][a-z0-9-]{1,31}$/
permissions
required

The entry’s permission keys the call needs: gmail.send.

Array<string>
>= 1 items unique items
as
required

Whose connection: person, the run’s person (the one it acts for, who started it or owns its trigger); company, the tenant’s.

Allowed values: person company
codeArtifactRef
One of:
object
kind
required
Allowed value: oci
imageRef
required
string
>= 1 characters
modulePath
required
string
>= 1 characters
artifactVersion
required
string
>= 1 characters
spec
One of:

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.

object
kind
required
Allowed value: http
method
required
string
Allowed values: GET POST PUT PATCH DELETE
urlTemplate
required

URL template with {param} placeholders substituted from the tool’s input at invoke time.

string
>= 1 characters
headers
Array<object>
object
name
required
string
>= 1 characters
value
required
string
authorization
One of:
object
kind
required
Allowed value: bearer
secretRef
required
object
envName
required
string
>= 1 characters
name
required
string
>= 1 characters
requestBody
One of:
object
kind
required
Allowed value: json-input
timeoutMs

Wall-clock timeout in ms. Default 30000.

integer
>= 1
parseJson

When true (default), the response body is parsed as JSON before returning to the invoker.

boolean
successStatus
object
min
required
integer
>= 100 <= 599
max
required
integer
>= 100 <= 599
unregisteredAt

Present only on an unregistered version: a retired tool (every version unregistered) as GET /v1/tools?includeRetired=true lists it.

string format: date-time
secretScopes

Where each secret it names is read, by name: recorded by the server when it was registered, never sent by a caller. null: none usable (the registrant administers no scope the secret could be read at), until an admin records it again: a tool by publishing a new version, an MCP endpoint by unregistering it and registering it again. Absent on items registered before it was recorded, or on a runtime without a secrets store.

object
key
additional properties
One of:
One of:
object
kind
required
string
Allowed value: tenant
Example
{
  "effects": [
    {
      "kind": "reads"
    }
  ],
  "transport": "auto",
  "sandbox": "none",
  "network": {
    "kind": "none"
  },
  "needsSpec": {
    "connections": {
      "additionalProperty": {
        "as": "person"
      }
    }
  },
  "codeArtifactRef": {
    "kind": "oci"
  },
  "spec": {
    "kind": "http",
    "method": "GET",
    "authorization": {
      "kind": "bearer"
    },
    "requestBody": {
      "kind": "json-input"
    }
  },
  "secretScopes": {
    "additionalProperty": {
      "kind": "tenant"
    }
  }
}

400

Section titled “400”

projectId is not a project id (a UUID).

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Section titled “401”

Missing / malformed / expired / revoked bearer token.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

Section titled “404”

No tool with that id under this tenant.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

410

Section titled “410”

Tool retired (all versions unregistered).

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

503

Section titled “503”

The database was too busy to answer in time (database-busy); Retry-After (whole seconds) says when to try again.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also