Skip to main content

Tools Configuration

In GenUI, Tools are Action Blocks that the model can call during a conversation. A tool is appropriate when the model needs fresh data or needs to perform work before it can answer.

Common uses:

  • Query APIs or databases
  • Run calculations
  • Fetch records by ID
  • Transform structured data
  • Trigger a workflow that still returns a useful result
warning

If the Action Block does not return anything, it cannot be used as a GenUI tool.

For each tool, GenUI includes:

  • Function name
  • Description
  • Parameters
  • Required or optional status
  • Parameter descriptions
  • Return type
  • Return description

That means the Action Block name and description matter. They are part of the tool-selection signal the model sees.

note

If a tool throws an exception, the error is caught and sent back to the model as a structured error payload. The UI remains stable and the model can explain the failure or suggest alternatives.

Tool Requirements​

The Action Block must return a value​

Tools are designed around request/response semantics. No return value means nothing meaningful can be sent back to the model.

Parameter and return types must be supported​

Supported tool types include:

  • String
  • int
  • double
  • bool
  • Color
  • DateTime
  • TimestampRange
  • LatLng
  • GooglePlace
  • JSON
  • DataStruct
  • Enum
  • media-path string types such as ImagePath, VideoPath, AudioPath, and MediaPath
  • list forms of the same supported types

Unsupported types are rejected during validation.

Duplicate tools are not allowed on the same widget​

Configuring the same Action Block twice on one GenUI widget is treated as an error.

Loading Messages​

Each tool can define its own loading message in the widget configuration.

  • If set, that message is shown while the tool runs.
  • If omitted, the generated tool uses Processing....

This is separate from the widget-level thinking message, which defaults to Thinking... and is shown before the tool call starts.

Serialization Rules​

The generated code serializes common FlutterFlow data types into model-friendly JSON:

  • Color: CSS color string. e.g., Color(0xFF4CAF50) → "#4CAF50"
  • DateTime: ISO 8601 string. e.g., DateTime(2024, 3, 15) → "2024-03-15T00:00:00.000"
  • TimestampRange: start|end milliseconds string. e.g., TimestampRange(1700000000000, 1700086400000) → "1700000000000|1700086400000"
  • LatLng: serialized string form. e.g., LatLng(37.7749, -122.4194) → "37.7749,-122.4194"
  • GooglePlace: serialized place payload (JSON object with place details)
  • DataStruct: converted using toMap(). e.g., Product(name: "Shoes", price: 99) → { "name": "Shoes", "price": 99 }
  • Enum: serialized enum string. e.g., OrderStatus.delivered → "delivered"

Best Practices​

Keep tools focused​

Prefer small, specific tools:

  • getOrderDetails
  • searchProducts
  • getWeatherForLocation
  • calculateQuote

over broad tools like:

  • handleRequest
  • fetchData
  • processWorkflow

Write descriptions for model behavior, not just for humans​

Good:

Retrieves the current order status, tracking number, and ETA for a given order ID.

Weak:

Looks up an order.

Return structured data when possible​

If the output can be represented as Custom Data Type DataStruct, do that instead of flattening everything into strings. Structured output is easier for the model to feed into catalog components.

Match tool output to catalog input​

Reliable GenUI setups usually follow this shape:

  • A tool returns OrderStruct
  • A catalog component accepts OrderStruct

That gives the model a clean path from retrieval to rendering.

Common Examples​

Data lookup​

getOrderDetails(orderId: String) -> OrderStruct

The model calls the tool, gets a structured order result, and renders an order summary component.

searchProducts(query: String, maxPrice: double?) -> List<ProductStruct>

The model calls the tool and then renders a list-style catalog component using the returned products.

Calculation​

calculateMonthlyPayment(amount: double, rate: double, termMonths: int) -> PaymentQuoteStruct

The model uses the result to explain the output and optionally render a quote component.