Tools - Colossal

Tools are LLM-callable functions. They are used by the AI Reasoning step inside agents and by the chat agent in the dashboard. Each tool has a kind. Read tools fetch data. Write tools mutate state and run through your configured approval policy before running.

Customers

Read tools

get_customer_details

Get customer details by UID or email. Returns email, full name, created_at, and order count.Input

customer_uid

string | null

The customer’s UUID

string | null

The customer’s email address

Output

customer_uid

string | null

full_name

string | null

created_at

string | null

order_count

integer | null

error

string | null

Write tools

create_customer

Create a new customer record.Input

string

required

Customer email address.

full_name

string

required

Customer full name.

Output

customer

CustomerOutput | null

Show properties

customer_id

integer

customer_uid

string

full_name

string

org_id

integer

update_customer

Update a customer record.Input

customer_id

integer

required

The customer’s database ID.

string | null

New email address.

full_name

string | null

New full name.

Output

customer

CustomerOutput | null

Show properties

customer_id

integer

customer_uid

string

full_name

string

org_id

integer

changed_fields

string[]

Insights

Read tools

query_insights

Query the workspace’s analytics data.Input

sql_query

string

required

Invoices

Read tools

get_invoice_details

Get invoice details by UID, including status, totals, line items, and billing info.Input

invoice_uid

string

required

The invoice’s UUID

Output

success

boolean

error

string | null

invoice_id

integer | null

invoice_uid

string | null

invoice_number

string | null

status

string | null

source

string | null

customer_id

integer | null

order_id

integer | null

currency

string | null

subtotal

integer | null

discount

integer | null

tax

integer | null

total

integer | null

bill_to_name

string | null

bill_to_email

string | null

line_items

InvoiceLineItemOutput[]

Show properties

line_item_id

integer

product_id

integer | null

title

string

quantity

integer

unit_price

integer

total

integer

Write tools

create_invoice

Create an invoice for a customer.Input

customer_id

integer

required

The customer’s database ID.

line_items

object[]

required

List of line items, each with description, quantity, unit_price.

currency

string

ISO 4217 currency code (default: usd). Default: "usd".

Output

invoice_id

integer | null

invoice_uid

string | null

status

string | null

total

integer | null

create_invoice_line_item

Append a line item to an existing invoice.Input

invoice_uid

string

required

The invoice’s UUID.

title

string

required

Line item title.

quantity

integer

required

Quantity (>=1).

unit_price

integer

required

Unit price in the invoice’s smallest currency unit.

product_id

integer | null

Optional product ID linking the item to a product.

description

string | null

Optional description.

Output

line_item_id

integer | null

invoice_id

integer | null

Notifications

Read tools

list_notifications

Browse workspace notifications with filters.Input

Orders

Read tools

get_order_details

Get order details by UID including line items and customer info.Input

order_uid

string

required

The order’s UUID

Output

integer | null

uid

string | null

status

string | null

subtotal

number | null

total

number | null

tax

number | null

created_at

string | null

customer

OrderCustomerInfo | null

Show properties

integer

uid

string

name

string

line_items

OrderLineItemInfo[] | null

error

string | null

get_order_history

Get a customer’s recent order history. Returns orders with totals, status, and line items.Input

customer_id

integer

required

The customer’s database ID

limit

integer

Max orders to return (default 20) Default: 20.

Output

order_count

integer

orders

OrderSummary[]

Show properties

integer | null

uid

string | null

status

string | null

subtotal

number | null

total

number | null

tax

number | null

created_at

string | null

customer

OrderCustomerInfo | null

Show properties

integer

uid

string

name

string

line_items

OrderLineItemInfo[] | null

get_orders

Browse the most recent orders.Input

limit

integer

Default: 10.

Write tools

update_billing_address

Update the billing address on an order.Input

order_uid

string

required

The order’s UUID.

line1

string

required

Street address line 1.

city

string

required

City name.

postal_code

string

required

Postal/ZIP code.

country

string

required

ISO country code (e.g. ‘US’).

line2

string | null

Optional secondary address line.

state

string | null

Optional state/region code.

Output

order_id

integer | null

update_order

Update fields on an order (whitelisted by the order’s workflow-updatable fields).Input

order_id

integer

required

The order’s database ID.

updates

object

required

Dict of writable fields to apply (subject to the order’s workflow-updatable whitelist).

Output

message

string | null

update_order_metadata

Update an order’s integration metadata.Input

order_id

integer

required

The order’s database ID.

metadata

object

required

Metadata fields to merge into the order record.

Output

order_id

integer | null

update_order_status

Update an order’s status. Pauses for approval before running.Input

order_id

integer

required

The order’s database ID.

status

enum (`pending`, `confirmed`, `complete`)

required

New status. Cannot be ‘refunded’ or ‘cancelled’ (those have dedicated flows).

Output

order_id

integer | null

previous_status

string | null

new_status

string | null

update_shipping_address

Update the shipping address on an order.Input

order_uid

string

required

The order’s UUID.

line1

string

required

Street address line 1.

city

string

required

City name.

postal_code

string

required

Postal/ZIP code.

country

string

required

ISO country code (e.g. ‘US’).

line2

string | null

Optional secondary address line.

state

string | null

Optional state/region code.

Output

order_id

integer | null

Payments

Read tools

get_payment_details

Get payment details by UID, including amount, status, and method.Input

payment_uid

string

required

The payment’s UUID

Output

success

boolean

error

string | null

payment_id

integer | null

payment_uid

string | null

invoice_id

integer | null

status

string | null

amount

integer | null

currency

string | null

payment_provider

string | null

payment_method

string | null

card_brand

string | null

card_last4

string | null

transaction_id

string | null

failure_code

string | null

failure_message

string | null

Products

Read tools

get_product_details

Get product details by UID, including name, description, archive state, and default variant.Input

product_uid

string

required

The product’s UUID

Output

success

boolean

error

string | null

product_id

integer | null

product_uid

string | null

name

string | null

handle

string | null

description

string | null

is_published

boolean | null

is_archived

boolean | null

default_variant

ProductVariantOutput | null

Show properties

uid

string

name

string | null

inventory_count

integer | null

prices

ProductPriceOutput[]

Show properties

uid

string

name

string | null

currency

string

unit_price

number | null

is_default

boolean

get_products

Browse the workspace’s products.Input

search_term

string | null

Write tools

archive_deliverable

Archive a product deliverable.Input

deliverable_uid

string

required

The deliverable’s UUID.

Output

deliverable_uid

string | null

archive_product

Archive a product so it stops appearing on the storefront.Input

product_uid

string

required

The product’s UUID.

Output

product_uid

string | null

create_deliverable

Create a new product deliverable.Input

type

string

required

Deliverable type identifier.

name

string

required

Display name.

config

object | null

Optional type-specific configuration.

Output

deliverable_uid

string | null

name

string | null

create_price

Create a new price for a product variant.Input

variant_uid

string

required

The variant’s UUID.

amount

number

required

Unit price.

currency

string

ISO 4217 currency code (default: USD). Default: "USD".

name

string | null

Optional human-readable name for the price.

recurring_interval

string | null

Optional ‘month’ or ‘year’ for subscriptions.

is_default

boolean

Whether to mark this as the default price for the variant. Default: false.

Output

price_uid

string | null

is_default

boolean | null

publish_product

Publish a product so it appears on the storefront.Input

product_uid

string

required

The product’s UUID.

Output

product_uid

string | null

name

string | null

set_default_price

Mark a price as the default for its variant.Input

price_uid

string

required

The price’s UUID.

Output

price_uid

string | null

unarchive_product

Unarchive a product.Input

product_uid

string

required

The product’s UUID.

Output

product_uid

string | null

update_deliverable

Update a product deliverable.Input

deliverable_uid

string

required

The deliverable’s UUID.

name

string | null

Optional new name.

type

string | null

Optional new type identifier.

config

object | null

Optional new configuration.

Output

deliverable_uid

string | null

Web

Read tools

fetch_page

Fetch the content of a public web page.Input

url

string

required

query

string

required

web_search

Search the public web.Input

query

string

required

num_results

integer

Default: 5.

​Customers

​Read tools

​Write tools

​Insights

​Read tools

​Invoices

​Read tools

​Write tools

​Notifications

​Read tools

​Orders

​Read tools

​Write tools

​Payments

​Read tools

​Products

​Read tools

​Write tools

​Web

​Read tools

Customers

Read tools

Write tools

Insights

Read tools

Invoices

Read tools

Write tools

Notifications

Read tools

Orders

Read tools

Write tools

Payments

Read tools

Products

Read tools

Write tools

Web

Read tools