# client.tools

> client.tools — the tools operations.

`client.tools` — the `tools` operations.

On `AsyncKindgi` every method is the same, awaited.

## `client.tools.list()`

```python signature
list(
    *,
    limit: int | None = None,
    cursor: str | None = None,
    name: str | None = None,
    scope_kind: Literal['tenant', 'org', 'project'] | None = None,
    scope_id: str | UUID | None = None,
    inherit: bool | None = None,
    include_retired: bool | None = None,
    timeout: float | None = None,
) -> ToolCollectionPage
```

List tools. `GET /v1/tools`

Cursor-paginated list of registered tool manifests. Optional `?name=` filters by prefix on tool id. A retired tool (every version unregistered) is listed only with `?includeRetired=true`, as its highest version with `unregisteredAt`, so it can be found and a version reinstated.

## `client.tools.register()`

```python signature
register(
    body: RegisterToolBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> RegisterToolResult
```

Register a tool manifest. `POST /v1/tools`

Body is a `ToolManifest` (Tool minus its runtime handler). Server validates via `@kindgi/tools.validateToolManifest`. Metadata only: the handler is not uploaded through this route and must already be available to the runtime. A tool never gets a model provider's key: one that declares (`needsSpec.secrets`) or sends (`spec.authorization.secretRef`) a secret a provider registration of the tenant names, in any env, is refused. Where each secret it names is read is recorded on the version (`secretScopes`): the first of its own scope, its project's org and the tenant that has the secret and that the caller administers, else the broadest they administer; the runtime reads it there only.

## `client.tools.get()`

```python signature
get(tool_id: str | UUID, /, *, timeout: float | None = None) -> Tool
```

Fetch a tool manifest (latest active version). `GET /v1/tools/{toolId}`

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).

## `client.tools.list_versions()`

```python signature
list_versions(
    tool_id: str | UUID,
    /,
    *,
    limit: int | None = None,
    cursor: str | None = None,
    include_tombstoned: bool | None = None,
    timeout: float | None = None,
) -> ToolVersionCollectionPage
```

List all versions of a tool. `GET /v1/tools/{toolId}/versions`

Cursor-paginated list of tool versions. Defaults to active versions only. Pass `?includeTombstoned=true` to include soft-tombstoned rows too; tombstoned rows carry `unregisteredAt` (ISO string), active rows do not.

## `client.tools.get_version()`

```python signature
get_version(
    tool_id: str | UUID,
    version: str,
    /,
    *,
    timeout: float | None = None,
) -> Tool
```

Fetch a specific tool version. `GET /v1/tools/{toolId}/versions/{version}`

## `client.tools.unregister()`

```python signature
unregister(
    tool_id: str | UUID,
    version: str,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
) -> UnregisterToolResult
```

Unregister a specific tool version. `POST /v1/tools/{toolId}/versions/{version}/unregister`

## `client.tools.reinstate_version()`

```python signature
reinstate_version(
    tool_id: str | UUID,
    version: str,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
) -> ReinstateToolVersionResult
```

Reinstate a specific tombstoned tool version. `POST /v1/tools/{toolId}/versions/{version}/reinstate`

Un-tombstones a previously-unregistered version: clears the tombstone on that version and recomputes the latest active version. Restores the manifest bytes verbatim (semver hygiene: reinstate never mutates). Idempotent — reinstating an active version is a no-op (returns `wasTombstoned: false`). Reinstating any version of a fully-retired tool reactivates the identity: subsequent GETs return 200, dispatch succeeds. Publish is always allowed regardless of retirement state — this verb is for restoring previously-unregistered bytes, not for reactivating a retired identity (a fresh publish does that).