---
title: "Read agent capabilities, scoped permissions and delivery"
method: GET
path: "/v1/tool-capabilities"
tags: ["Tool Permissions"]
---

# Read agent capabilities, scoped permissions and delivery

`GET /v1/tool-capabilities`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/tool-capabilities`
- Auth: HTTP bearer

The tool policy generation this caller may inspect. Each row is one tool
with its operations; an operation carries its included and excluded
coverage, its scoped permission rules and a permission summary.
The status also lists delivery per context (mode and budget band, and
whether the context follows the app default) and the capability
narrowing per client or profile. Membership, permission and
delivery are separate facts: an included tool can be denied, and an
excluded tool can carry an Allow. `generationId` and `catalogId` are what
a preview must name, and `canEdit` says whether this caller may prepare
and apply commands. Requires `tools:read`.

## Response `200`

The caller's view of the current generation

- ToolCapabilityStatus
  - `generationId` string, required
  - `catalogId` string, required
  - `canEdit` boolean, required
  - `rows` ToolCapabilityRow[], required
    - `id` string, required
    - `name` string, required
    - `title` string, required
    - `operations` ToolCapabilityOperation[], required
      - `id` string, required
      - `label` string, required
      - `inclusion` 'included' | 'partial' | 'excluded' | 'unavailable', required
      - `supportedSelectors` string[], required
      - `includedCoverage` ToolCapabilityCoverage[], required
        - `operationId` string, required
        - `reachRevision` integer, required
        - `resourceKind` string, required
        - `resourceType` string
        - `installationId` string
        - `rawName` string
        - `contractFingerprint` string
        - `selector` ToolCapabilitySelector, required
          - `kind` 'all' | 'project' | 'resource', required
          - `id` string: The project or resource id; absent for `all`.
      - `excludedCoverage` ToolCapabilityCoverage[], required
        - `operationId` string, required
        - `reachRevision` integer, required
        - `resourceKind` string, required
        - `resourceType` string
        - `installationId` string
        - `rawName` string
        - `contractFingerprint` string
        - `selector` ToolCapabilitySelector, required
          - `kind` 'all' | 'project' | 'resource', required
          - `id` string: The project or resource id; absent for `all`.
      - `rules` ToolCapabilityRule[], required
        - `id` string, required
        - `coverage` ToolCapabilityCoverage, required
          - `operationId` string, required
          - `reachRevision` integer, required
          - `resourceKind` string, required
          - `resourceType` string
          - `installationId` string
          - `rawName` string
          - `contractFingerprint` string
          - `selector` ToolCapabilitySelector, required
            - `kind` 'all' | 'project' | 'resource', required
            - `id` string: The project or resource id; absent for `all`.
        - `policy` string, required
        - `subject` ToolCapabilitySubject, required
          - `kind` 'agents' | 'client' | 'appWide', required
          - `client` ToolCapabilityClientKey: The stable identity of a client; never a token id.
            - `kind` 'connected-app' | 'shared-class' | 'paired-device' | 'provider-ticket' | 'person', required
            - `id` string: The clientId, class name, pair-row key or ticket id; absent for `person`.
            - `mintOrigin` string
        - `lifetime` ToolCapabilityLifetime, required
          - `kind` 'persistent' | 'expiresAt' | 'session', required
          - `value` string: The expiry instant or session id, when the kind needs one.
        - `origin` string
        - `authorKind` string, required
        - `authorClient` ToolCapabilityClientKey: The stable identity of a client; never a token id.
          - `kind` 'connected-app' | 'shared-class' | 'paired-device' | 'provider-ticket' | 'person', required
          - `id` string: The clientId, class name, pair-row key or ticket id; absent for `person`.
          - `mintOrigin` string
        - `authorDetail` string
      - `permissionSummary` string, required
      - `unavailableReason` string
      - `updatedSinceAllowed` boolean: Present, and true, only when the operation asks because an update reset an Allow the person chose for an earlier version of it. Absent otherwise.
    - `inclusion` 'included' | 'partial' | 'excluded' | 'unavailable', required
    - `availabilityReason` string
    - `unavailableReason` string
  - `delivery` ToolCapabilityDelivery[], required
    - `contextId` string, required
    - `mode` string, required
    - `band` string, required: The numeric budget band (lean, balanced or heavy).
    - `inherited` boolean: True when the context follows the app default.
  - `narrowing` ToolCapabilityNarrowing[], required
    - `id` string, required
    - `kind` string, required
    - `subjectKind` string, required
    - `subjectId` string
    - `client` ToolCapabilityClientKey: The stable identity of a client; never a token id.
      - `kind` 'connected-app' | 'shared-class' | 'paired-device' | 'provider-ticket' | 'person', required
      - `id` string: The clientId, class name, pair-row key or ticket id; absent for `person`.
      - `mintOrigin` string
    - `coverage` ToolCapabilityCoverage[], required
      - `operationId` string, required
      - `reachRevision` integer, required
      - `resourceKind` string, required
      - `resourceType` string
      - `installationId` string
      - `rawName` string
      - `contractFingerprint` string
      - `selector` ToolCapabilitySelector, required
        - `kind` 'all' | 'project' | 'resource', required
        - `id` string: The project or resource id; absent for `all`.

## Other responses

- `403`: The bearer lacks `tools:read`, or the request no longer has management access (`administration_forbidden`).
- `503`: The policy generation is unavailable (`administration_unavailable`); nothing is guessed.

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)