Creating Tools

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.

---

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.

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

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

---