List Tool Groups

Beta

GET/v1/ai/tool-groups

This endpoint is idempotent. Learn more

Returns a paginated list of the groups the agent tool catalog is organized into.

The catalog is platform-defined and identical for every account. Pagination applies to the groups themselves, so a group requested with include=tools always carries its complete tool list regardless of the page limit. The q search term matches against group names.

Permissions requiredValues:agents:read

The role behind your API key or agent must grant every one of these permissions.

cursoroptional string

Opaque cursor token identifying where the page of results starts.

Use the cursor value embedded in a previous response's next_page_url or previous_page_url to fetch the adjacent page. Omit to start from the first page.

limitoptional integer

Maximum number of results to return in a single page.

qoptional string

Free-text search term used to filter results.

Which fields are matched against the term varies by endpoint.

include[]optional arrayenumValues:tools

Sub-objects to expand in the response. When omitted, sub-objects are returned as null.

objectstringenumValues:list

Resource type identifier.

page_infoobject

Pagination metadata.

next_page_urlstringnullable

Relative URL that fetches the next page of results.

previous_page_urlstringnullable

Relative URL that fetches the previous page of results.

has_next_pageboolean

Whether more results exist after this page.

has_prev_pageboolean

Whether results exist before this page.

dataarray of tool_group

Resources in this page.

idstring

Group ID.

objectstringenumValues:tool_group

Resource type identifier.

namestring

Human-readable group name (e.g. Product Tools).

descriptionstringnullable

Description of what the tools in this group do.

slugstring

Machine-readable name for the group (e.g. customer_tools).

iconstring

Icon identifier (e.g. a Material Icon name).

sort_orderinteger

Display sort order, lowest first.

toolslistExpandablenullable

Tools belonging to this group.

objectstringenumValues:list

Resource type identifier.

page_infoobject

Pagination metadata.

next_page_urlstringnullable

Relative URL that fetches the next page of results.

previous_page_urlstringnullable

Relative URL that fetches the previous page of results.

has_next_pageboolean

Whether more results exist after this page.

has_prev_pageboolean

Whether results exist before this page.

dataarray of available_tool

Resources in this page.

objectstringenumValues:available_tool

Resource type identifier.

slugstring

A stable identifier used when attaching the tool to an agent.

categorystring

Where the tool's behavior comes from.

built_in: a capability implemented by the agent runtime itself, such as fetching a web page or drafting a reply for a teammate to approve.
api_endpoint: an operation of this API exposed as a tool, letting the agent perform it on the account's behalf.

namestring

Human-readable name for the tool.

descriptionstringnullable

Explanation of what the tool does.

This is also the description the agent's model reads when deciding whether to call the tool.

config_schemaobjectnullable

JSON schema describing the configuration options this tool accepts.

Defines the shape of the config field on AgentDefinitionTool: a schema declaring a max_results integer property means that tool's config may set max_results.

Encoded as a JSON value (object, array, string, number, boolean, or null), not a JSON-encoded string.

required_permissionsarray of string

Permission scopes the agent's role must hold for this tool to be usable (e.g. products:read).

required_role_typestringnullable

Role type the caller must have for this tool, when the operation is gated by role rather than a permission (e.g. admin).

mutatingboolean

Whether invoking this tool takes an action rather than only reading data.

True for any api_endpoint tool whose underlying operation is not a read, and for built_in tools that do something externally visible or hard to undo, such as sending an email. A mutating built_in tool always pauses its run for human approval and that gate cannot be turned off for an individual agent; for api_endpoint tools the flag is advisory and review stays configurable per agent.

Responses

200

Successful response for List Tool Groups

List Tool Groups

import Augno from '@augno/sdk';

const client = new Augno({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const listToolGroup = await client.ai.retrieveToolGroups();

console.log(listToolGroup.data);

import Augno from '@augno/sdk';

const client = new Augno({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const listToolGroup = await client.ai.retrieveToolGroups();

console.log(listToolGroup.data);

200 example

{
  "object": "list",
  "page_info": {
    "next_page_url": "/v1/ai/tool-groups?cursor=eyJjIjoiMjAyNi0wNS0xMFQwMDowMDowMFoiLCJzIjoidGdycF9pbWphcXByenVxdjUiLCJkIjoiZiJ9.7kd0-fX5XsAB_qPNGOreyXQQ1BwwCyda_zK_lQs0-5Y",
    "previous_page_url": null,
    "has_next_page": true,
    "has_prev_page": false
  },
  "data": [
    {
      "id": "tgrp_imjaqprzuqv5",
      "object": "tool_group",
      "name": "Customer Tools",
      "description": "Tools for looking up and managing customers.",
      "slug": "customer_tools",
      "icon": "people",
      "sort_order": 0,
      "tools": {
        "object": "list",
        "page_info": {
          "next_page_url": null,
          "previous_page_url": null,
          "has_next_page": false,
          "has_prev_page": false
        },
        "data": [
          {
            "object": "available_tool",
            "slug": "read_doc",
            "category": "built_in",
            "name": "Lookup Customer",
            "description": "Look up a customer by their email address.",
            "config_schema": null,
            "required_permissions": [
              "customers:read"
            ],
            "required_role_type": null,
            "mutating": false
          }
        ]
      }
    }
  ]
}

{
  "object": "list",
  "page_info": {
    "next_page_url": "/v1/ai/tool-groups?cursor=eyJjIjoiMjAyNi0wNS0xMFQwMDowMDowMFoiLCJzIjoidGdycF9pbWphcXByenVxdjUiLCJkIjoiZiJ9.7kd0-fX5XsAB_qPNGOreyXQQ1BwwCyda_zK_lQs0-5Y",
    "previous_page_url": null,
    "has_next_page": true,
    "has_prev_page": false
  },
  "data": [
    {
      "id": "tgrp_imjaqprzuqv5",
      "object": "tool_group",
      "name": "Customer Tools",
      "description": "Tools for looking up and managing customers.",
      "slug": "customer_tools",
      "icon": "people",
      "sort_order": 0,
      "tools": {
        "object": "list",
        "page_info": {
          "next_page_url": null,
          "previous_page_url": null,
          "has_next_page": false,
          "has_prev_page": false
        },
        "data": [
          {
            "object": "available_tool",
            "slug": "read_doc",
            "category": "built_in",
            "name": "Lookup Customer",
            "description": "Look up a customer by their email address.",
            "config_schema": null,
            "required_permissions": [
              "customers:read"
            ],
            "required_role_type": null,
            "mutating": false
          }
        ]
      }
    }
  ]
}

List Tool Groups

Authorization

Query Parameters

Returns

Responses