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 domain is available for purchase

Create a tool to fetch weather data for a given city

Help me build a tool that calculates shipping costs based on weight and destination

I want to validate email addresses and check if the domain has MX records 

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 the email parameter

Include a timeout parameter with default of 30 seconds

Change the output to also return the domain registrar 

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:

• CUSTOMER_FETCH - Fetch a customer record
• EMAIL_SEND - Send an email
• INVOICE_CREATE - Create an invoice

 Good: LEAD_QUALIFY, ORDER_TOTAL_CALCULATE
Bad: qualifyLead, calculate-order-total 

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: "Qualify a lead based on company size, industry, and budget. 
Returns score 0-100 and tier (A/B/C)."

Bad: "Qualifies leads" 

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:

 @YOUR_TOOL_NAME param1="value" param2=123 

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 CUSTOMER_FETCH to also return the customer's last order 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_DELETE
• Email - EMAIL_SEND , EMAIL_VALIDATE , EMAIL_TEMPLATE_RENDER
• Billing - INVOICE_CREATE , PAYMENT_PROCESS , SUBSCRIPTION_UPDATE

Composition Principles

Build Small, Compose Large

Don’t build monolithic tools:

 ❌ CUSTOMER_ONBOARD_AND_EMAIL_AND_SYNC

✅ CUSTOMER_CREATE → EMAIL_WELCOME_SEND → CRM_SYNC
   (Three 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

---