---
title: "Get a tool"
method: GET
path: "/v1/tools/{id}"
tags: ["Agents"]
---

# Get a tool

`GET /v1/tools/{id}`

## Request

- Base URL: `https://api.pyai.com`
- URL: `https://api.pyai.com/v1/tools/{id}`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

## Path parameters

- `id` string, required

## Response `200`

Tool

- Tool
  - `object` string
  - `id` string
  - `org_id` string, nullable
  - `name` string
  - `kind` 'prebuilt' | 'custom'
  - `description` string
  - `input_schema` object
  - `config_schema` ToolConfigSchema: Declares the settings a tool needs. Render these as a form in your agent builder; capture answers on the agent's tool binding config.
    - `fields` ToolConfigField[]
      - `key` string, required
      - `label` string, required
      - `type` 'string' | 'number' | 'boolean' | 'select', required
      - `required` boolean
      - `secret` boolean: When true, the value is encrypted at rest and never returned in plaintext.
      - `help` string
      - `placeholder` string
      - `options` string[]: Allowed values when type is 'select'.
  - `webhook_url` string, nullable
  - `execution` 'hosted' | 'server' | 'engine' | 'client': How the tool runs. hosted = PyAI runs it (prebuilt read catalog). server = the tool-executor calls your webhook. engine = the Omni call engine runs it natively (call control: transfer_to_human, send_dtmf, play_hold, collect, end_call), not routed to the executor. client = your connected app.
  - `auth_header` string, nullable
  - `has_auth` boolean: Whether a webhook auth secret is configured (the secret itself is never returned).
  - `side_effect` 'read' | 'action'
  - `timeout_ms` integer
  - `status` 'active' | 'disabled'
  - `created_at` integer

## Other responses

- `401`: Missing or invalid API key (`code: unauthorized`)
- `404`: No such tool

---

[API](https://skmtc.dev/pyai/apis/pyai-api.md) · [All operations](https://skmtc.dev/pyai/apis/pyai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pyai/apis/pyai-api/revisions/819d8e7c4d09?raw)