Tool Calling

tool_calling_process:
  - step: 1
    name: Input Processing
    description: User query is received by the agent
    example: 'User: "What''s the weather in Tokyo?"'

  - step: 2
    name: Tool Identification
    description: LLM analyzes the query and identifies the need for weather data
    selected_tool: get_weather

  - step: 3
    name: Parameter Preparation
    description: Extract and map entities to tool parameters
    parameters:
      location: Tokyo
      units: celsius

  - step: 4
    name: Tool Invocation
    description: Platform triggers the tool with the prepared parameters

  - step: 5
    name: Execution
    description: Tool performs its operation (API call, computation, etc.)

  - step: 6
    name: Result Processing
    description: Validate and format the tool output
    result:
      temp: 22
      condition: Sunny
      humidity: 45

  - step: 7
    name: Response Generation
    description: Agent incorporates results into natural language
    example: "It's currently 22°C and sunny in Tokyo."

name: get_weather
description: |
  Retrieves current weather conditions for a specified location.
  Returns temperature, conditions (sunny, cloudy, rainy), humidity,
  and wind speed. Use when users ask about weather or need to plan
  outdoor activities.

parameters:
  location:
    type: string
    description: City name or coordinates (for example, "Tokyo" or "35.6762,139.6503")
    required: true

  units:
    type: string
    enum: [celsius, fahrenheit]
    description: Temperature unit preference
    default: celsius

# Good - Specific and actionable
description: |
  Retrieves the current status of a customer order including
  shipping information and tracking number. Use when customers
  ask about order status, delivery dates, or tracking.

# Bad - Too vague
description: Gets order information.

User: "What's my order status and when will it arrive?"

1. get_order_status(order_id) → status, tracking_number
2. get_shipping_estimate(tracking_number) → delivery_date

Response: "Your order shipped yesterday. Based on tracking,
          it should arrive by Friday."

User: "Compare the weather in Tokyo and New York"

┌─ get_weather(location="Tokyo") ────┐
│                                    ├─→ Compare and respond
└─ get_weather(location="New York") ─┘

Response: "Tokyo is 22°C and sunny, while New York is 15°C
          and cloudy. Tokyo is warmer by 7 degrees."

Agent receives: "I need to book a flight and hotel"

Agent reasoning:
├── Task requires travel booking
├── Available tools: search_flights, book_flight, search_hotels, book_hotel
├── User hasn't specified details yet
└── Action: Ask for dates and destination, then use tools

Agent: "I can help with that. Where are you traveling to,
       and what are your dates?"

ai_node:
  prompt: "Process this customer request"
  tools:
    - check_inventory
    - create_order
    - send_confirmation
  tool_choice: auto  # auto, required, none

# Force tool usage
tool_choice: required

# Disable tools
tool_choice: none

# Use specific tool
tool_choice:
  type: specific
  tool: get_order_status

{
  "trace_id": "trace_abc123",
  "tool_calls": [
    {
      "tool": "get_order_status",
      "parameters": { "order_id": "ORD-12345" },
      "started_at": "2024-01-15T14:30:00.123Z",
      "completed_at": "2024-01-15T14:30:00.456Z",
      "duration_ms": 333,
      "status": "success",
      "result": { "status": "shipped", "tracking": "1Z999..." }
    }
  ]
}

# Include: What it does, when to use it, what it returns
description: |
  Searches the product catalog by keyword, category, or filters.
  Returns matching products with names, prices, and availability.
  Use when users ask about products, want recommendations, or
  are looking for specific items.

# Too broad - hard for LLM to know when to use
name: do_everything
description: Handles all customer operations

# Too narrow - creates tool sprawl
name: get_order_status_for_shipped_orders
name: get_order_status_for_processing_orders

# Just right - clear scope
name: get_order_status
description: Gets status for any order by order ID

if (!params.order_id) {
  return {
    error: "order_id is required",
    message: "Please provide an order number"
  };
}