---
title: Creating Tools
description: Functions that agents, workflows, and views use to take action
icon: Wrench
---

import Callout from "../../../../components/ui/Callout.astro";


## Understanding Tools
Tools are functions that perform specific actions - they're the "verbs" of your AI application.

Each tool:
- **Does one thing well** - Perform CRUD operation, save to database, call an API
- **Has defined inputs** - Parameters the tool accepts
- **Returns structured output** - Predictable data format
- **Can be called by** - Agents, workflows, views, and other tools

**Where tools come from:**
- **Integrations** - Install apps from the store (Gmail, Slack, Notion, etc.) to get pre-built tools that automatically appear in your workspace
- **Custom tools** - Build your own using deco chat or write TypeScript manually

**Strategy:** Start by browsing available integrations in the deco store. Most common needs are already covered. Build custom tools only for specific requirements that don't exist yet.

## Creating Tools with Deco Chat

The easiest way to create tools is by describing what you need:

**Example prompts:**
```
I need a tool that checks if a product is in stock across all warehouses

Create a tool to calculate discounts based on customer loyalty tier

Help me build a tool that recommends products based on customer purchase history

I want to validate customer email addresses and send welcome discount codes
```

**What happens next:**
1. Deco chat asks clarifying questions (What inputs? What should it return?)
2. Suggests a schema based on your needs
3. Creates the tool using `@TOOLS_CREATE`
4. You test and iterate together

**Refine as you go:**
```
Add validation to ensure the customer has a valid loyalty account

Include a minimum order total parameter with default of $50

Change the output to also return the discount expiration date
```

This conversational approach means you start with a rough idea and iterate toward exactly what you need.

<Callout type="info">
  The sections below explain the mechanics if you want to understand how tools work.
</Callout>

---

## What Goes on Under the Hood?

When you create a tool (whether via deco chat or by clicking the code icon to write TypeScript), these are the key components being defined:

### 1. Tool Name

Tools follow the `RESOURCE_ACTION` pattern with `UPPERCASE_WITH_UNDERSCORES`:

**Examples:**
- `PRODUCT_INVENTORY_CHECK` - Check product inventory levels
- `ORDER_CONFIRMATION_SEND` - Send order confirmation email
- `CART_DISCOUNT_APPLY` - Apply discount to shopping cart

```
Good: CUSTOMER_LOYALTY_UPDATE, PRODUCT_PRICE_CALCULATE
Bad: updateLoyalty, calculate-product-price
```

**Why this matters:** Agents use tool names to decide when to use them. Descriptive names = better decisions.

### 2. Description

Tells agents and workflows what the tool does and when to use it:
```
Good: "Check product inventory across all warehouses and calculate available stock.
Returns total quantity, location breakdown, and low stock alert status."

Bad: "Checks inventory"
```

The better the description, the better agents understand when to use it.

### 3. Input Schema

Defines what parameters the tool accepts:
- **Required** vs **optional** fields
- **Default values** where sensible
- **Validation** rules (email format, URL, number ranges)
- **Types** (string, number, boolean, etc.)

Keep it simple, if you need 10+ parameters, consider breaking into smaller tools.

### 4. Output Schema

Defines what the tool returns:
- **Structure** - What fields are returned
- **Types** - Data types for each field
- **Success/failure indicator**
- **Error details** when failures occur

This schema is critical for:
- **Workflows** - Can reference specific output fields in next steps
- **Agents** - Know what data they received and how to use it
- **Composability** - Other tools can consume this output

### 5. Tool Logic

The actual implementation, what the tool does:

**Common patterns:**
- **Chain existing tools** - Compose tools from installed integrations
- **API calls** - Fetch data from external services
- **Database operations** - Query or modify data
- **Transformations** - Process and format data

When you ask deco chat to create a tool, it handles all of this for you. When you write TypeScript, you define these explicitly.

### 6. Testing

Once created, test your tool in two ways:

**Via UI:**
deco CMS automatically generates a form based on your input schema. Fill in the fields and run the tool to see results.

**Via chat:**
```
@PRODUCT_INVENTORY_CHECK sku="SKU-12345"
@ORDER_CONFIRMATION_SEND customerEmail="customer@example.com" orderNumber="ORD-789"
```

Iterate until it works as expected.

## Discovering Existing Tools

Before creating a tool, check what already exists:

**Browse workspace tools:**
- Go to **Tools** in the sidebar to see all available tools
- Use search to find specific actions (e.g., "email", "customer")

**Browse integration tools:**
- Visit **Apps** 
- Check installed integrations for pre-built tools
- Browse **Store** to discover new integrations
- Each integration shows what tools it provides
- Install and configure the integration to add those tools to your workspace

**Add custom integrations:**

If you built your own MCP server or want to connect to a custom app:

1. Click **Add Custom** in the Apps section
2. Fill in the connection details:
   - **Name** - A friendly name for this app (e.g., "My Sales API")
   - **Description** - What this app does (optional)
   - **Type** - How to connect (usually HTTP for web-based apps)
   - **URL** - The web address where your app is hosted (e.g., `https://example.com/mcp`)
   - **Token** - A password or key to access your app securely (optional)
3. Click **Add** to connect

Once connected, any tools your custom app provides will automatically appear in your workspace and can be used by agents, workflows, and views.

<Callout type="info">
  **For non-tech users:** You'll typically receive the URL and token from whoever built the custom app. Just copy and paste those values into the form.
</Callout>

## Managing Tools

**Updating tools:**

Ask deco chat to make changes or edit TypeScript directly:

```
Update PRODUCT_INVENTORY_CHECK to also return the product's reorder threshold
Update ORDER_CONFIRMATION_SEND to include estimated delivery date
```

**Other actions:**

Hover over any tool card and click **...** to:
- Duplicate the tool
- Delete the tool (note: this affects any agents, workflows, or views using it)
- View tool details

## Tool Groups

Organize related tools for easier discovery:

**Examples:**
- **Customer Management** - `CUSTOMER_CREATE`, `CUSTOMER_FETCH`, `CUSTOMER_UPDATE`, `CUSTOMER_LOYALTY_UPDATE`
- **Order Processing** - `ORDER_CREATE`, `ORDER_UPDATE`, `ORDER_CANCEL`, `ORDER_REFUND`
- **Inventory** - `PRODUCT_INVENTORY_CHECK`, `INVENTORY_UPDATE`, `INVENTORY_ALERT_CREATE`
- **Notifications** - `ORDER_CONFIRMATION_SEND`, `SHIPPING_NOTIFICATION_SEND`, `CART_ABANDONED_SEND`

## Composition Principles

### Build Small, Compose Large

Don't build monolithic tools:
```
❌ ORDER_CREATE_AND_EMAIL_AND_UPDATE_INVENTORY_AND_NOTIFY

✅ ORDER_CREATE → INVENTORY_UPDATE → ORDER_CONFIRMATION_SEND → ORDER_NOTIFICATION_SEND
   (Four simple tools composed in a workflow)
```

### Schemas Enable Automation

Clear input/output schemas let:
- Agents know when and how to use the tool
- Workflows auto-map data between steps
- Views generate forms automatically
- Errors catch before runtime

<Callout type="warning">
  Tools that delete data, charge payments, or call expensive APIs should have restricted permissions. Configure access controls to limit who can use sensitive tools.
</Callout>

## Common Mistakes

**Avoid these pitfalls:**

1. **Overly complex tools** - If a tool needs 10+ parameters, break it into smaller tools
2. **Vague descriptions** - Agents can't use tools they don't understand
3. **Missing error handling** - Always return clear error messages
4. **No validation** - Validate inputs before processing
5. **Unclear naming** - Use the `RESOURCE_ACTION` pattern consistently

---