Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ansa.so/llms.txt

Use this file to discover all available pages before exploring further.

​
What Are Tools?

Tools extend what your AI agent can do beyond answering questions. With tools, your agent can:
  • Fetch data from external APIs (product info, order status, weather)
  • Display rich content (product cards, carousels, tables)
  • Collect information through interactive forms
  • Trigger actions in your systems (create tickets, send notifications)
Tools dashboard

​
Tool Types

Ansa supports three types of tool execution:
TypeDescriptionUse Case
httpMakes HTTP requests to APIsFetch data, trigger webhooks
formDisplays interactive formsCollect user information
mockReturns static/templated responsesTesting, demos

​
Creating a Tool

Navigate to Agent → Tools → Create Tool:

​
Basic Configuration

Every tool needs:
FieldDescriptionExample
NameUnique identifier (lowercase, underscores)search_products
DescriptionWhen should the AI use this tool?”Search for products when user asks about items”
Input SchemaParameters the tool acceptsSee below

​
Naming Conventions

Tool names must:
  • Start with a letter or underscore
  • Use only lowercase letters, numbers, and underscores
  • Be unique within the agent
Pattern: /^[a-z_][a-z0-9_]*$/ ✅ search_products, get_order_status, contact_form ❌ Search Products, get-order, 123tool

​
Input Schema

Define what parameters the AI should provide: 
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "The search term to look for"
    },
    "category": {
      "type": "string",
      "description": "Product category to filter by",
      "enum": ["electronics", "clothing", "home"]
    },
    "limit": {
      "type": "number",
      "description": "Maximum number of results"
    }
  },
  "required": ["query"]
}
Write clear descriptions for each property. The AI uses these to understand what values to provide.

​
How the AI Uses Tools

When a user sends a message, the AI:
  1. Analyzes the user’s request
  2. Decides if a tool would help answer it
  3. Extracts the required parameters from the conversation
  4. Calls the tool with those parameters
  5. Processes the result and responds naturally
The AI decides to use a tool based on the tool’s description. Write descriptions that clearly explain when the tool should be used: Good descriptions:
  • “Search for products when the user asks about items, prices, or availability”
  • “Look up order status when user provides an order number or asks about shipping”
  • “Show the contact form when user wants to reach support or has an issue you cannot resolve”
Poor descriptions:
  • “Product search” (too vague)
  • “Use this tool” (no context)

​
Tool Execution Flow

User Message
    ↓
AI analyzes request
    ↓
AI decides to use tool
    ↓
Ansa executes tool
    ├── HTTP: Makes API request
    ├── Form: Returns schema to widget
    └── Mock: Returns templated response
    ↓
Result returned to AI
    ↓
AI generates natural response
    ↓
Response + rich display sent to user

​
Enabling/Disabling Tools

Toggle tools on/off without deleting them:
  • Enabled — AI can use this tool
  • Disabled — Tool is hidden from AI
Useful for:
  • Seasonal tools (holiday promotions)
  • A/B testing different tools
  • Temporarily disabling broken integrations

​
Tool Categories

Organize your tools by purpose:
CategoryExamples
Data LookupProduct search, order status, user info
FormsContact, lead capture, surveys
ActionsCreate ticket, send notification
DisplayShow pricing table, feature comparison

​
Next Steps

HTTP Tools

Connect to external APIs

Form Tools

Collect user information

Display Configuration

Show rich content

Marketplace

Install pre-built tools

​
See Also