> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List available tools
> Returns the catalog of tools the caller's organization can attach to an agent.
The default response is filtered to only include tools the org can use right now:
- Tools requiring an integration are excluded if the org hasn't connected it
- Private tools are excluded unless enabled by an org admin
- Companion tools (auto-attached when their parent is enabled) are excluded
Each entry's `name` + `parameters` + `description` matches the shape stored
under an agent's `tools` JSONB. To attach a tool to an agent, copy the
relevant entries from this response into the `tools` field of `POST /agents`,
keyed by `name`. Provider tools (`isProviderTool: true`) are passed under
their `name` (e.g., `google:code_execution`) with `{ isProviderTool: true }`.
The set of available tools changes as integrations are connected, private
tools are toggled in org settings, and new platform tools ship. Call this
endpoint at agent-build time rather than caching the catalog.
## OpenAPI
````yaml /openapi.yaml get /tools
openapi: 3.1.0
info:
title: AsterAgents API
version: 1.0.0
description: >
API for AsterAgents platform operations.
- **Admin endpoints** (`/admin/*`) require organization admin privileges
(`org:admin` role)
- **Agent endpoints** (`/agents`) require agent management permissions or
`org:admin` role
- **Knowledge base endpoints** (`/kb/*`) require standard authentication
- **Skills endpoints** (`/skills/*`) require standard authentication
- **File endpoints** (`/upload/*`, `/kb/files`, `/skills/files`) require
standard authentication
contact:
name: AsterAgents Support
url: https://asteragents.com/support
servers:
- url: https://asteragents.com/api
description: Production
- url: http://localhost:3000/api
description: Local development
security:
- bearerAuth: []
tags:
- name: Users
description: Manage active organization users
- name: Invitations
description: Manage organization invitations
- name: Files
description: Upload and manage files
- name: Knowledge Bases
description: Manage knowledge bases and their files
- name: Knowledge Base Management
description: Create, update, and delete knowledge bases
- name: Agents
description: Create, update, and delete agents
- name: Agent Tags
description: Organize agents with tags
- name: Tools
description: Discover the tool catalog available to your organization
- name: Skills
description: Manage agent skills
- name: Skill Files
description: Manage bundled files for skills
- name: Conversations
description: Invoke agents and retrieve conversation history and messages
- name: Scheduled Tasks
description: Schedule agents to run automatically on a cron schedule
paths:
/tools:
get:
tags:
- Tools
summary: List available tools
description: >
Returns the catalog of tools the caller's organization can attach to an
agent.
The default response is filtered to only include tools the org can use
right now:
- Tools requiring an integration are excluded if the org hasn't connected it
- Private tools are excluded unless enabled by an org admin
- Companion tools (auto-attached when their parent is enabled) are excluded
Each entry's `name` + `parameters` + `description` matches the shape
stored
under an agent's `tools` JSONB. To attach a tool to an agent, copy the
relevant entries from this response into the `tools` field of `POST
/agents`,
keyed by `name`. Provider tools (`isProviderTool: true`) are passed
under
their `name` (e.g., `google:code_execution`) with `{ isProviderTool:
true }`.
The set of available tools changes as integrations are connected, private
tools are toggled in org settings, and new platform tools ship. Call this
endpoint at agent-build time rather than caching the catalog.
operationId: listTools
parameters:
- name: all
in: query
description: |
When `true`, include every tool with `available: false` and an
`unavailableReason` instead of filtering them out. Useful for
surfacing "connect this integration to unlock X" hints.
schema:
type: boolean
default: false
responses:
'200':
description: Tool catalog retrieved successfully
content:
application/json:
schema:
type: object
required:
- tools
- total
properties:
tools:
type: array
items:
$ref: '#/components/schemas/ToolCatalogEntry'
total:
type: integer
description: Number of tools returned
examples:
filtered:
summary: Default — only tools available to the org
value:
total: 3
tools:
- name: scrape_url
displayName: Scrape URL
description: >-
Scrape content from a given URL using the Firecrawl
API
category: Research
requiredIntegration: null
isPrivate: false
available: true
parameters:
type: object
required:
- url
properties:
url:
type: string
description: The URL to scrape
- name: search_knowledge_base
displayName: Search Knowledge Base
description: >-
Search through a specific knowledge base for relevant
information.
category: Aster Agents Platform
requiredIntegration: null
isPrivate: false
available: true
parameters:
type: object
required:
- query
- knowledge_base_id
properties:
query:
type: string
description: The search query
knowledge_base_id:
type: integer
description: The ID of the knowledge base to search
- name: google:code_execution
displayName: Code Execution
description: Generate and run Python code
category: Google AI
isProviderTool: true
provider: google
available: true
all:
summary: With `?all=true` — includes unavailable tools
value:
total: 2
tools:
- name: salesforce_query
displayName: Salesforce Query
description: Run SOQL queries against the org's Salesforce instance
category: Salesforce
requiredIntegration: salesforce
isPrivate: false
available: false
unavailableReason: missing_integration
parameters:
type: object
required:
- soql
properties:
soql:
type: string
description: SOQL query to execute
- name: melink_contract_review
displayName: Contract Review
description: >-
Log contract review results and send notification
emails
category: Private
requiredIntegration: null
isPrivate: true
available: false
unavailableReason: private_not_enabled
parameters:
type: object
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
components:
schemas:
ToolCatalogEntry:
type: object
required:
- name
- displayName
- description
- category
- available
properties:
name:
type: string
description: >
Tool identifier. Use this as the key under an agent's `tools` JSONB.
Provider tools use a `provider:tool` form (e.g.,
`google:code_execution`).
example: scrape_url
displayName:
type: string
description: Human-readable label
example: Scrape URL
description:
type: string
description: What the tool does
category:
type: string
description: Display grouping for the tool picker
example: Research
parameters:
type: object
nullable: true
description: |
JSON Schema for the tool's call arguments. Drop this object verbatim
into the agent's `tools[name]` payload alongside `description`.
Omitted for provider tools (the AI provider supplies the schema).
additionalProperties: true
requiredIntegration:
type: string
nullable: true
description: |
Connection key the org must have configured for this tool to run
(e.g., `salesforce`, `hubspot`, `box`). Null for tools with no
external integration.
example: salesforce
isPrivate:
type: boolean
description: |
Private tools must be enabled by an org admin via
`enabledPrivateTools` in org settings before they can be attached.
isProviderTool:
type: boolean
description: |
True for provider built-in tools. Provider tools are attached by
adding `{ "isProviderTool": true }` under their `name` in the
agent's `tools` JSONB — they have no `parameters` schema here.
provider:
type: string
description: AI provider that owns the tool (provider tools only)
example: google
available:
type: boolean
description: Whether the org can attach this tool right now
unavailableReason:
type: string
enum:
- missing_integration
- private_not_enabled
description: |
Set only when `available` is false (typically only returned with
`?all=true`). Indicates why the tool is unavailable.
Error:
type: object
required:
- error
properties:
error:
type: string
example: Bad Request
details:
type: array
items:
type: object
additionalProperties: true
responses:
BadRequest:
description: Bad Request - Invalid parameters or user not part of organization
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: User is not part of any organization
InternalServerError:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Internal Server Error
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: |
JWT token from Clerk authentication.
Must be from a user with `org:admin` role.
````