---
title: "list agent tools"
method: GET
path: "/tools"
tags: ["Dataset CRUD"]
---

# list agent tools

`GET /tools`

## Request

- Base URL: `https://api.riveterhq.com/v1`
- URL: `https://api.riveterhq.com/v1/tools`
- Auth: HTTP bearer

The tools an enrichment may name in `only_tools` / `additional_tools`, or pin to an output column (`tool`): what each does, what a call takes (`inputs`; `input_groups` when any one complete set of them is enough) and gives back (`returns`), its credits per call (`price_note` when the price settles after the call: `pdf` and `image` by the tokens their model spends reading the file, `text_search_pdf` per page, the LinkedIn email / phone tools only on a contact), whether it is on by default, and whether it is enabled on this account. Some tools call their provider with your own API key (`requires_api_key`, linked under Settings > API keys). `budget` is the per-row credit range and the per-column default.

## Response `200`

The tool catalog for this account

- ToolCatalog
  - `tools` object[]
    - `name` string: The name to use in only_tools / additional_tools
    - `description` string
    - `credits_per_call` number
    - `price_note` string, nullable: When the price is not flat — the scrape settles to its outcome, pdf and image to the tokens their model spent reading the file (credits_per_call is what is booked before the call), text_search_pdf to the PDF's page count; the LinkedIn email / phone tools are charged only when the call returns a contact. Null for a flat price.
    - `default` boolean: On without being named
    - `requires_opt_in` boolean: A Riveter admin enables it on the account; false for the default tools and the ones any account may add
    - `enabled` boolean: Usable on this account (opt-in satisfied or not needed; says nothing about the API key)
    - `requires_api_key` boolean: Calls its provider with the account's own API key (Apollo, Hunter, Findymail, curl, USPTO); refused until one is linked under Settings > API keys
    - `api_key_linked` boolean, nullable: Whether the account has linked a key for this tool; null when the tool needs none
    - `companions` string[]: Free helper tools this tool brings along
    - `inputs` object[]: What a call takes. On a pinned column the agent fills these from the row's columns or its research, so the dataset should carry them (a LinkedIn URL column for the LinkedIn tools, a domain for the Hunter domain search).
      - `name` string
      - `type` string, nullable: string / integer / number / boolean / object; null when the input takes more than one shape
      - `required` boolean
      - `description` string, nullable
    - `input_groups` array[], nullable: When set, any one complete group of inputs is enough (`[["linkedin_handle"], ["domain", "full_name"]]`) and `required` is false on each
      - string[]
    - `returns` string, nullable: What a call gives back — on a pinned column, what the cell holds
  - `budget` object
    - `default_credits_per_output_column` number: A new enrichment's budget per row is this times its output columns; it moves by this much per column added or removed until locked
    - `min_credits_per_row` number
    - `max_credits_per_row` number

## Other responses

- `401`: Missing or invalid API key (`request_status` body — see the AuthError schema)
- `403`: The API key's account may not access this resource or endpoint (`forbidden`), or the account has not migrated to Datasets yet (`feature_not_enabled` — open Datasets in the app and click "Migrate to Datasets")

## Changes

- **2026-11-13** `fac56b649559`: 2 info
  - api tag `Dataset CRUD` added
  - api tag `Datasets` removed
- **2026-10-30** `dcb4d45ade1a`: 2 info
  - added the optional property `error/credit_detail/estimate/oneOf[#/components/schemas/CreditEstimate]/typical` to the response with the `403` status
  - added the optional property `error/credit_detail/estimate/oneOf[#/components/schemas/CreditEstimate]/upfront` to the response with the `403` status
- **2026-10-19** `76aabcc5686b`: 2 info
  - api tag `Datasets` added
  - api tag `Datasets (beta)` removed
- **2026-10-16** `7ebb804e781e`: 1 warning, 3 info
  - removed the optional property `tools/items/parameters` from the response with the `200` status
  - added the optional property `tools/items/input_groups` to the response with the `200` status
  - added the optional property `tools/items/inputs` to the response with the `200` status
  - added the optional property `tools/items/returns` to the response with the `200` status
- **2026-10-16** `5af893c5bc21`: 1 info
  - added the optional property `tools/items/parameters` to the response with the `200` status

[Operation history](https://skmtc.dev/riveterhq/apis/riveter-api/changes/tools/get.md)

---

[API](https://skmtc.dev/riveterhq/apis/riveter-api.md) - [All operations](https://skmtc.dev/riveterhq/apis/riveter-api/llms.txt) - [OpenAPI document](https://skmtc.dev/riveterhq/apis/riveter-api/revisions/fac56b649559?raw)