Response Fields

Response fields control how data is displayed in your tools. You can customise field labels, visibility, ordering, and formatting to create clear, informative interfaces for your users.

Basic configuration

Response field configuration is defined in the tool's JSON file under the response property. Each field is referenced by its JSON path:

tools/list-orders.json

{
  "action_name": "listOrders",
  "response": {
    "$.results.reference": {
      "display_name": "Order Ref"
    },
    "$.results.totalAmount": {
      "display_name": "Total",
      "help_text": "Order total including tax"
    }
  }
}

Available options

Option	Type	Description
`display_name`	string	Label shown in the UI instead of the field name
`display_order`	number	Position of the field (lower numbers appear first)
`visible`	boolean	Whether the field is shown
`help_text`	string	Explanatory text shown alongside the field
`visible_condition`	string	CEL expression controlling visibility
`section_name`	string	Groups field into a named section
`image_preview`	boolean	For file fields, shows inline image previews
`link`	object	Links the field to another tool

Field visibility

By default, all response fields are visible. You can hide fields or show them conditionally:

tools/get-order.json

{
  "action_name": "getOrder",
  "response": {
    "$.id": {
      "visible": false
    },
    "$.internalNotes": {
      "visible_condition": "ctx.identity.hasRole('Admin')"
    }
  }
}

The visible_condition accepts CEL expressions that can reference:

ctx.identity - The authenticated user
Response field values using $.fieldName

Field ordering

Fields are displayed in the order defined in your schema by default. Use display_order to override this:

tools/list-stock-items.json

{
  "action_name": "listStockItems",
  "response": {
    "$.results.sku": {
      "display_order": 1
    },
    "$.results.name": {
      "display_order": 2
    },
    "$.results.quantity": {
      "display_order": 3
    }
  }
}

Lower numbers appear first. Fields without explicit ordering appear after ordered fields.

Linking to other tools

Response fields can link to other tools, enabling navigation between related records. This is especially useful for ID fields and relationships:

tools/list-order-items.json

{
  "action_name": "listOrderItems",
  "response": {
    "$.results.product.id": {
      "link": {
        "tool_id": "get-product",
        "data_mapping": [
          {
            "key": "id",
            "path": { "path": "$.product.id" }
          }
        ]
      }
    }
  }
}

Link options

Option	Type	Description
`tool_id`	string	The ID of the target tool (action name in kebab-case)
`data_mapping`	array	Maps response values to the target tool's inputs
`title`	string	Label for the link
`as_dialog`	boolean	Opens the linked tool in a dialog instead of navigating
`visible_condition`	string	CEL expression controlling when the link appears

Field formatting

Field formatting controls how values are displayed in the UI. You can format numbers as currencies, add colour to enum values, or mask sensitive data.

Field formatting is configured in _fields.json, not in individual tool files. This ensures consistent formatting across all tools.

Configuring field formats

Create a _fields.json file in your tools/ directory:

tools/_fields.json

[
  {
    "id": "Order.totalAmount",
    "format": {
      "number_config": {
        "mode": "CURRENCY",
        "currency_code": "GBP"
      }
    }
  },
  {
    "id": "OrderStatus",
    "format": {
      "enum_config": {
        "values": [
          { "value": "Pending", "colour": "#f59e0b" },
          { "value": "Shipped", "colour": "#3b82f6" },
          { "value": "Delivered", "colour": "#22c55e" }
        ]
      }
    }
  }
]

The id field uses the format:

ModelName.fieldName for model fields
EnumName for enum types

Number formatting

Number fields can be formatted as decimals, currencies, percentages, or with units.

Format modes

Mode	Description	Example output
`DECIMAL`	Standard decimal display (default)	`1,234.56`
`RAW`	No formatting applied	`1234.56`
`CURRENCY`	Currency with symbol	`£1,234.56`
`PERCENTAGE`	Percentage display	`12.5%`
`UNIT`	Display with unit suffix	`150 kg`

Currency formatting

tools/_fields.json

[
  {
    "id": "Order.totalAmount",
    "format": {
      "number_config": {
        "mode": "CURRENCY",
        "currency_code": "USD"
      }
    }
  }
]

The currency_code should be an ISO 4217 currency code (e.g. GBP, USD, EUR).

Percentage formatting

tools/_fields.json

[
  {
    "id": "Product.discountRate",
    "format": {
      "number_config": {
        "mode": "PERCENTAGE"
      }
    }
  }
]

Unit formatting

tools/_fields.json

[
  {
    "id": "StockItem.weight",
    "format": {
      "number_config": {
        "mode": "UNIT",
        "unit_code": "kilogram"
      }
    }
  }
]

The unit_code supports compound units like meter-per-second.

Number formatting options

Option	Type	Description
`mode`	string	`DECIMAL`, `RAW`, `CURRENCY`, `PERCENTAGE`, or `UNIT`
`currency_code`	string	ISO 4217 currency code (for `CURRENCY` mode)
`unit_code`	string	Unit identifier (for `UNIT` mode)
`locale`	string	Locale code for formatting (auto-detected by default)
`prefix`	string	Text prepended to the value
`suffix`	string	Text appended to the value
`sensitive`	boolean	Masks the value until hovered
`colourise`	string	Colour mode: `NONE`, `NORMAL`, `INVERTED`, or `CUSTOM`

Conditional colouring for numbers

Use the colourise option to colour numbers based on their value:

tools/_fields.json

[
  {
    "id": "StockItem.quantity",
    "format": {
      "number_config": {
        "mode": "DECIMAL",
        "colourise": "NORMAL"
      }
    }
  }
]

Colourise mode	Behaviour
`NONE`	No colour applied (default)
`NORMAL`	Positive values green, negative values red
`INVERTED`	Positive values red, negative values green
`CUSTOM`	Custom colours (not yet implemented)

Enum formatting

Enum fields can display custom labels and colours for each value. This is useful for status fields where visual distinction helps users scan data quickly.

tools/_fields.json

[
  {
    "id": "OrderStatus",
    "format": {
      "enum_config": {
        "values": [
          {
            "value": "Pending",
            "display_value": "Awaiting Processing",
            "colour": "#f59e0b"
          },
          {
            "value": "Processing",
            "display_value": "In Progress",
            "colour": "#3b82f6"
          },
          {
            "value": "Shipped",
            "colour": "#8b5cf6"
          },
          {
            "value": "Delivered",
            "colour": "#22c55e"
          },
          {
            "value": "Cancelled",
            "colour": "#ef4444"
          }
        ]
      }
    }
  }
]

Enum value options

Option	Type	Description
`value`	string	The actual enum value in your schema
`display_value`	string	Label shown in the UI (defaults to `value`)
`colour`	string	Hex colour code for the badge
`display_order`	number	Order in dropdowns and filters

Colours are displayed as coloured badges in tables and record views. Use colours that have good contrast and are accessible.

Boolean formatting

Boolean fields can be customised with labels and colours for each state:

tools/_fields.json

[
  {
    "id": "StockItem.inStock",
    "format": {
      "bool_config": {
        "positive_value": "In Stock",
        "positive_colour": "#22c55e",
        "negative_value": "Out of Stock",
        "negative_colour": "#ef4444"
      }
    }
  }
]

Boolean formatting options

Option	Type	Description
`positive_value`	string	Label when value is `true`
`positive_colour`	string	Hex colour when value is `true`
`negative_value`	string	Label when value is `false`
`negative_colour`	string	Hex colour when value is `false`

String formatting

String fields support prefixes, suffixes, colour, and URL previews.

Adding prefix and suffix

tools/_fields.json

[
  {
    "id": "Order.reference",
    "format": {
      "string_config": {
        "prefix": "ORD-"
      }
    }
  }
]

URL previews

For fields containing URLs, enable link previews:

tools/_fields.json

[
  {
    "id": "Product.websiteUrl",
    "format": {
      "string_config": {
        "show_url_preview": true
      }
    }
  }
]

Sensitive data

Mask sensitive values that should be hidden by default:

tools/_fields.json

[
  {
    "id": "Customer.apiKey",
    "format": {
      "string_config": {
        "sensitive": true
      }
    }
  }
]

Sensitive fields show masked content until the user hovers over them.

String formatting options

Option	Type	Description
`prefix`	string	Text prepended to the value
`suffix`	string	Text appended to the value
`text_colour`	string	Hex colour for the text
`show_url_preview`	boolean	Renders URLs as clickable links
`sensitive`	boolean	Masks the value until hovered

Image previews

For file fields that contain images, enable inline previews:

tools/list-products.json

{
  "action_name": "listProducts",
  "response": {
    "$.results.image": {
      "image_preview": true
    }
  }
}

This displays a thumbnail of the image directly in the table or record view.

Complete example

Here's a complete example showing various response field configurations for an order management system:

tools/_fields.json

[
  {
    "id": "Order.totalAmount",
    "format": {
      "number_config": {
        "mode": "CURRENCY",
        "currency_code": "GBP"
      }
    }
  },
  {
    "id": "Order.discountPercentage",
    "format": {
      "number_config": {
        "mode": "PERCENTAGE"
      }
    }
  },
  {
    "id": "OrderStatus",
    "format": {
      "enum_config": {
        "values": [
          { "value": "Pending", "colour": "#f59e0b" },
          { "value": "Processing", "colour": "#3b82f6" },
          { "value": "Shipped", "colour": "#8b5cf6" },
          { "value": "Delivered", "colour": "#22c55e" },
          { "value": "Cancelled", "colour": "#ef4444" }
        ]
      }
    }
  },
  {
    "id": "Order.isPriority",
    "format": {
      "bool_config": {
        "positive_value": "Priority",
        "positive_colour": "#ef4444",
        "negative_value": "Standard",
        "negative_colour": "#6b7280"
      }
    }
  }
]

tools/list-orders.json

{
  "action_name": "listOrders",
  "response": {
    "$.results.reference": {
      "display_name": "Order Ref",
      "display_order": 1
    },
    "$.results.customer.id": {
      "display_name": "Customer",
      "display_order": 2,
      "link": {
        "tool_id": "get-customer",
        "data_mapping": [
          {
            "key": "id",
            "path": { "path": "$.customer.id" }
          }
        ]
      }
    },
    "$.results.status": {
      "display_order": 3
    },
    "$.results.totalAmount": {
      "display_name": "Total",
      "display_order": 4
    },
    "$.results.createdAt": {
      "display_name": "Order Date",
      "display_order": 5
    },
    "$.results.internalNotes": {
      "visible": false
    }
  }
}

This configuration:

Formats the total as British pounds
Shows discount as a percentage
Adds colour badges to the order status
Customises priority display with colours
Reorders and renames columns in the list view
Links customer IDs to the customer detail view
Hides internal notes from the default view

Input Fields Field Formatting