Transform Tools

Transform tools process data using JSONata expressions. They're lightweight and don't require external API calls.

Creating a Transform Tool

create_dynamic_tool({
  name: "calculate_discount",
  description: "Calculate discounted price",
  tool_type: "transform",
  input_schema: {
    type: "object",
    properties: {
      price: { type: "number" },
      discount_percent: { type: "number" }
    },
    required: ["price", "discount_percent"]
  },
  transform_config: {
    expression: "input.price * (1 - input.discount_percent / 100)"
  },
  activate: true
})

JSONata Basics

JSONata is an expression language for JSON. Access input via input.field.

Simple Access

input.name           // Get the name field
input.user.email     // Nested access
input.items[0]       // Array index

Built-in Functions

$uppercase(input.text)       // "HELLO"
$lowercase(input.text)       // "hello"
$trim(input.text)           // Remove whitespace
$length(input.array)        // Array length
$sum(input.numbers)         // Sum of array
$average(input.numbers)     // Average of array

Transformations

// Map array
$map(input.items, function($v) { $v.name })

// Filter array
$filter(input.items, function($v) { $v.active })

// Sort array
$sort(input.items, function($a, $b) { $a.price - $b.price })

Example: Extract Emails

create_dynamic_tool({
  name: "extract_emails",
  description: "Extract email addresses from text",
  tool_type: "transform",
  input_schema: {
    type: "object",
    properties: {
      text: { type: "string" }
    },
    required: ["text"]
  },
  transform_config: {
    expression: "$match(input.text, /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}/g)"
  }
})

Example: Format Name

create_dynamic_tool({
  name: "format_full_name",
  description: "Format first and last name",
  tool_type: "transform",
  input_schema: {
    type: "object",
    properties: {
      first_name: { type: "string" },
      last_name: { type: "string" },
      format: { type: "string", enum: ["full", "initials", "last_first"] }
    },
    required: ["first_name", "last_name"]
  },
  transform_config: {
    expression: `
      input.format = 'initials'
        ? $substring(input.first_name, 0, 1) & '.' & $substring(input.last_name, 0, 1) & '.'
        : input.format = 'last_first'
          ? input.last_name & ', ' & input.first_name
          : input.first_name & ' ' & input.last_name
    `
  }
})

Example: Data Summary

create_dynamic_tool({
  name: "summarize_numbers",
  description: "Get statistics for a list of numbers",
  tool_type: "transform",
  input_schema: {
    type: "object",
    properties: {
      numbers: { type: "array", items: { type: "number" } }
    },
    required: ["numbers"]
  },
  transform_config: {
    expression: `{
      "count": $count(input.numbers),
      "sum": $sum(input.numbers),
      "average": $average(input.numbers),
      "min": $min(input.numbers),
      "max": $max(input.numbers)
    }`
  }
})

Common Patterns

Object Construction

{
  "name": input.firstName & " " & input.lastName,
  "email": $lowercase(input.email),
  "created": $now()
}

Conditional Logic

input.score >= 90 ? "A" :
input.score >= 80 ? "B" :
input.score >= 70 ? "C" : "F"

String Operations

$join(input.tags, ", ")                    // Array to string
$split(input.text, ",")                    // String to array
$replace(input.text, "old", "new")         // Replace text
$substringBefore(input.email, "@")         // Get username

JSONata vs JavaScript

Transform tools use JSONata, not JavaScript:

For complex logic requiring full JavaScript, use Code Tools instead.

Reference

Full JSONata documentation: jsonata.org

Common functions:

• $string() - Convert to string
• $number() - Convert to number
• $boolean() - Convert to boolean
• $now() - Current timestamp
• $uuid() - Generate UUID