An agent.tool automation is the work behind an agent tool record. An AI agent calls the tool, this runs, and the content: it returns is what the model reads back.

inputs:
  text/query:
    description: What to look up in the handbook
    required@bool: yes

start:
  data.query:
    inputs:
      query: type:kb_article content:{{inputs.query}} limit:5
    output: results
  return:
    content@text:
      {% for row in results.rows %}
      - {{row.title}}: {{row.excerpt}}
      {% endfor %}

• The inputs block is the schema
• Inputs
• Outputs
• The environment of the call
• One automation, several tools
• An agent tool can't await
• Starter template

The inputs block is the schema

The automation declares its own inputs:, and that block is the schema the model is shown. Its description, required, allowed_values, and default are what the model reads and obeys, and they're also what the script reads back as inputs.<name>.

There's no second place to declare them. The agent tool record supplies what an automation has nowhere to say – the name the model calls, the description it reads, the transcript's icon and wording – and nothing about the arguments.

Every input is advertised to the model as a string regardless of its declared type, because a provider takes JSON scalars and a record/ input is a name or an id to the model either way.

Inputs

The automation dictionary starts with the following values:

Outputs

return:
  content: There are 12 open tickets in that group.

The environment of the call

A tool is handed where it was called from, not only what the model asked for. That's what lets a tool refuse work that doesn't belong where it was invoked – an action that's fine from a mail reply and wrong from a portal visitor's chat, or one that only makes sense beside the automation editor.

start:
  decision:
    outcome/wrong_place:
      if@bool: {{transcript_surface != 'mail_reply' ? 'yes'}}
      then:
        return:
          content: This tool only runs beside a mail reply.
    outcome/proceed:
      then:
        return:
          content: {{reply_draft}}

transcript_trigger says which kind of conversation this is – a worker's chat, a website visitor's, another agent's – while transcript_surface says which screen a worker's chat is open beside.

One automation, several tools

Because the agent tool record owns the schema, one automation can back several tool records. Branch on tool_name to tell them apart rather than writing a script per tool:

start:
  decision:
    outcome/search:
      if@bool: {{tool_name == 'search_handbook' ? 'yes'}}
      then:
        return:
          content: {{handbook_results}}
    outcome/read:
      if@bool: {{tool_name == 'read_handbook' ? 'yes'}}
      then:
        return:
          content: {{handbook_page}}

An automation's Usage panel lists the agent tools that reference it, resolved by looking them up rather than by scanning every script for the automation's name.

An agent tool can't await

An agent tool runs to completion inside a single tool call. There's no continuation to resume into, so it returns a content: string and can never await:.

An await: at any depth in the script is refused when the automation is saved, with a message saying to return content: instead.

Starter template

Automations » Build » AI Agent Tool seeds a working script on this trigger, together with the agent tool record that calls it.