ECA Tool

ECA Tool bridges ECA and the Tool API in two directions:

• Every tool registered with the Tool API becomes an ECA action, so an ECA model can invoke it.
• Every ECA model event of type "Tool" becomes a tool, so an AI agent or any other Tool API consumer can invoke an ECA model.

Running a tool from an ECA model

Every tool plugin registered with the Tool API, except the tools that this module itself derives from ECA models (see below), is available in ECA's action list as Tool: . Configuring this action lets you set each tool input, name the ECA tokens that receive the tool's outputs, and name a token that receives the structured execution result.

Input modes

Each tool input is configured in one of up to three modes, selected per input:

Leaving an input empty lets the tool apply its own default. FALSE, 0 and '0' are valid configured values and are all handed to the tool.

Outputs and the result token

Each tool output can be named to an ECA token (default: the output's own name); leave the field empty to discard that output.

The result token (default name tool_result) receives a structured value with these properties:

Example

A model that sends an email through a hypothetical mail_send tool, reading the recipient from a token and branching on the outcome:

1. Action Tool: Send email
   • Input to, mode "Token or plain value", value [node:author:mail]
   • Input subject, mode "Native widget", value Your content was published
   • Output message_id named to token sent_message_id
   • Result token name mail_result
2. Condition: token mail_result:success equals true
   • On true: log sent_message_id.
   • On false: log mail_result:message and mail_result:failure_category.

calculateDependencies() adds a module dependency on the tool's provider module, so exporting this model records that the site needs the module that supplies mail_send.

Exposing an ECA model as a tool

Add an event of type "Tool" to an ECA model. Each such event becomes one tool, identified internally as eca:::.

Event configuration keys

The arguments/outputs YAML grammar

Both configuration values share one grammar, one entry per input or output:

plain:
  data_type: string
  label: 'Plain'
  description: 'A plain input.'
account:
  data_type: 'entity:user'
  label: 'Account'
  description: 'An account.'
items:
  data_type: list
  label: 'Items'
  description: 'A list of items.'
  item_definition:
    data_type: string
    label: 'Item'
    description: 'A single item.'
settings:
  data_type: map
  label: 'Settings'
  description: 'A map of settings.'
  properties:
    inner:
      data_type: integer
      label: 'Inner'
      description: 'An inner property.'
annotated:
  data_type: string
  label: 'Annotated'
  description: 'Carries every annotation.'
  required: true
  multiple: false
  default_value: ~
  locked: false
  examples: ['alpha', 'beta']
  constraints:
    Length: { max: 255 }

Notes:

• data_type is required; every other key is optional.
• locked and examples are read for arguments only; outputs ignores them.
• item_definition (for data_type: list) and properties (for data_type: map) recurse into the same grammar.
• data_type: entity or any entity: value builds an entity-typed definition; list and map build their respective container definitions; every other value builds a plain scalar definition.
• An entry without a data_type key, or one whose value is a non-array, is silently dropped.

Writing an output: the "Set tool output" action

Inside the event's reaction chain, use the "Set tool output" action to provide a value for a declared output:

• output_name: the name of the output to write, matching a top-level key in outputs. Left empty, it targets the default output tool_output.
• output: the value, either a token, a plain string, or YAML when "Interpret above config value as YAML format" is enabled.

Setting an output name that the event does not declare, when the event declares at least one named output, fails the action's access check rather than being silently dropped.

Access control

Executing an ECA tool requires the execute eca tools permission, unless the backing event's permission key names a different permission — in that case only the named permission is checked. The execute eca tools permission is declared with restrict access: true because an ECA model can run arbitrary business logic; grant it only to trusted roles.

In the other direction, the Tool action that wraps a Tool API tool for use inside an ECA model calls that tool's own access() check before executing it. A tool's access control is therefore always enforced, whether it is called directly through the Tool API or through an ECA model.

Requirements reporting

A tool's checkRequirements() is advisory: it is surfaced as a warning when configuring the Tool action, and in drush tool:info, but it never blocks configuration or execution. For a tool derived from an ECA model, unmet requirements mean the backing model is missing, disabled, or no longer contains the event that the tool was derived from.