Tools & Functions

Tools extend your AI agent's capabilities beyond text generation, allowing it to interact with APIs, databases, and external services.

How Tools Work

1. You define tools with a name, description, and input schema
2. The AI model decides when to use a tool based on the user's query
3. FlowStack executes the tool and returns the result to the model
4. The model incorporates the result into its response

The model never calls tools directly — FlowStack mediates the execution, ensuring security and logging.

Defining Tools

HTTP Request Tool

Call any REST API:

{
  "name": "get_weather",
  "description": "Get current weather for a city",
  "type": "http_request",
  "config": {
    "method": "GET",
    "url": "https://api.weatherapi.com/v1/current.json",
    "params": {
      "key": "{{env.WEATHER_API_KEY}}",
      "q": "{{city}}"
    }
  },
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "City name (e.g., 'San Francisco')"
      }
    },
    "required": ["city"]
  }
}

Database Query Tool

Query FlowStack Tables:

{
  "name": "search_products",
  "description": "Search the product catalog by name or category",
  "type": "table_query",
  "config": {
    "table_id": "tbl_abc123",
    "filter_columns": ["name", "category"],
    "return_columns": ["name", "price", "description", "stock"]
  },
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search term for product name or category"
      }
    },
    "required": ["query"]
  }
}

Integration Tool

Use any FlowStack integration action as a tool:

{
  "name": "send_slack_message",
  "description": "Send a message to a Slack channel",
  "type": "integration",
  "config": {
    "piece": "slack",
    "action": "send_message",
    "connection_id": "conn_xyz789"
  },
  "parameters": {
    "type": "object",
    "properties": {
      "channel": {
        "type": "string",
        "description": "Slack channel name (e.g., #general)"
      },
      "message": {
        "type": "string",
        "description": "The message text to send"
      }
    },
    "required": ["channel", "message"]
  }
}

Tool Best Practices

• Write clear descriptions — The AI model uses the description to decide when to use the tool
• Keep parameter schemas simple — Complex nested schemas confuse models
• Set required fields — Mark essential parameters as required
• Handle errors gracefully — Tools should return informative error messages, not crash
• Limit tool count — 3–8 tools per agent is optimal. Too many tools degrades selection accuracy.
• Test tool selection — Verify the model picks the right tool for different queries