Tools

Tools allow your agent to perform actions and interact with external systems. Each tool has a unique identifier, description, and implementation.

Basic Structure

tools:
  - id: search_orders
    description: "Search for customer orders"
    parameters:
      - name: customer_id
        type: string
        description: "Customer ID"
        required: true
      - name: order_status
        type: enum
        values: ["pending", "shipped", "delivered", "cancelled"]
        description: "Filter by order status"
        required: false
    implementation:
      type: http
      method: GET
      url: "https://api.example.com/orders"
      headers:
        Authorization: "${env.API_KEY}"

Tool Types

1. HTTP Tools

tools:
  - id: get_weather
    description: "Get weather information"
    parameters:
      - name: location
        type: string
        required: true
    implementation:
      type: http
      method: GET
      url: "https://api.weather.com/current"
      headers:
        Authorization: "${env.WEATHER_API_KEY}"
      query_params:
        location: "${location}"

2. Function Tools

tools:
  - id: calculate_total
    description: "Calculate order total"
    parameters:
      - name: items
        type: array
        required: true
    implementation:
      type: function
      path: "./calculations.js"
      function: "calculateTotal"

3. MCP Tools

MCP tools are special tools that are provided by MCP servers. They allow your agent to interact with external services that follow the Model Context Protocol specification. MCP tools are defined on the server side and can be discovered and used by your agent.

tools:
  - id: search_products
    description: "Search for products"
    parameters:
      - name: query
        type: string
        required: true
    implementation:
      type: mcp_tool
      server: product_knowledge
      name: "search_products"

When using MCP tools, the actual implementation is provided by the MCP server, making it easier to integrate with external services while maintaining a consistent interface in your agent.

Parameter Types

1. String

parameters:
  - name: customer_name
    type: string
    description: "Customer's full name"
    required: true

2. Number

parameters:
  - name: amount
    type: number
    description: "Transaction amount"
    required: true
    min: 0
    max: 10000

3. Boolean

parameters:
  - name: include_details
    type: boolean
    description: "Include detailed information"
    required: false
    default: false

4. Enum

parameters:
  - name: status
    type: enum
    values: ["active", "inactive", "pending"]
    description: "Account status"
    required: true

5. Array

parameters:
  - name: items
    type: array
    description: "List of items"
    required: true
    items:
      type: string

6. Object

parameters:
  - name: address
    type: object
    description: "Customer address"
    required: true
    properties:
      street:
        type: string
        required: true
      city:
        type: string
        required: true
      country:
        type: string
        required: true

Implementation Types

1. HTTP Implementation

implementation:
  type: http
  method: POST
  url: "https://api.example.com/orders"
  headers:
    Authorization: "${env.API_KEY}"
    Content-Type: "application/json"
  body: |
    {
      "customer_id": "${customer_id}",
      "items": ${items}
    }    
  response:
    success: "${status === 200}"
    data: "${body}"

2. Function Implementation

implementation:
  type: function
  path: "./utils.js"
  function: "processOrder"
  timeout: 5000  # milliseconds

3. MCP Tool Implementation

implementation:
  type: mcp_tool
  server: order_system
  name: "create_order"
  schema:
    inputSchema:
      type: "object"
      properties:
        customer_id:
          type: "string"
        items:
          type: "array"
          items:
            type: "string"

Error Handling

tools:
  - id: process_payment
    description: "Process a payment"
    parameters:
      - name: amount
        type: number
        required: true
    implementation:
      type: http
      method: POST
      url: "https://api.example.com/payments"
    error_handling:
      retry:
        max_attempts: 3
        backoff: "exponential"
      fallback:
        type: function
        path: "./fallback.js"
        function: "handlePaymentError"

Complete Example

Here’s a complete tool configuration:

tools:
  - id: process_order
    description: "Process a new order"
    parameters:
      - name: customer_id
        type: string
        description: "Customer ID"
        required: true
      - name: items
        type: array
        description: "List of items to order"
        required: true
        items:
          type: object
          properties:
            product_id:
              type: string
              required: true
            quantity:
              type: number
              required: true
              min: 1
      - name: shipping_address
        type: object
        description: "Shipping address"
        required: true
        properties:
          street:
            type: string
            required: true
          city:
            type: string
            required: true
          country:
            type: string
            required: true
    implementation:
      type: http
      method: POST
      url: "https://api.example.com/orders"
      headers:
        Authorization: "${env.API_KEY}"
        Content-Type: "application/json"
      body: |
        {
          "customer_id": "${customer_id}",
          "items": ${items},
          "shipping_address": ${shipping_address}
        }        
      response:
        success: "${status === 200}"
        data: "${body}"
    error_handling:
      retry:
        max_attempts: 3
        backoff: "exponential"
      fallback:
        type: function
        path: "./fallback.js"
        function: "handleOrderError"

Best Practices

Clear Descriptions: Provide clear, concise descriptions
Parameter Validation: Define strict parameter types and constraints
Error Handling: Implement proper error handling and fallbacks
Security: Use environment variables for sensitive data
Documentation: Document tool behavior and requirements
Testing: Test tools thoroughly before deployment

Next Steps

Learn about States
Explore Flow Patterns
Read Best Practices

Last updated on May 9, 2025

MCP Servers States