Tool configuration reference

A tool group is one YAML definition file plus the code files it references. The definition file lists the group's tools and skills, the parameters each tool takes, the Python callable that runs the tool, and the dependency files the group needs. You upload it on the Tools screen; this page is the format reference the Tools page links to.

For the portal workflow — creating a group, uploading files, attaching it to an agent, and testing in the Playground — see Tools. This page covers the file format only. For YAML syntax itself, see YAML basics.

Writing the definition file and the Python implementation is a developer task.

Top-level keys

A definition file starts with kind: Plugin and then lists the group's tools and skills.

Key	Required	Value
kind	Yes	Must be Plugin.
name	Yes	The tool group name. The portal fills the Name field from this value and locks it; the name must be unique in your tenant.
description	Yes	A short description of the group. Fills the Description field.
dependencies	No	A list of file paths the group needs — the implementation code and, when the code uses third-party packages, a requirements.txt. See Dependencies.
tools	No	A list of tool objects the agent can call during a conversation. See Declare a tool.
skills	No	A list of skill objects that run automatically at fixed points in a conversation. See Declare a skill.

A minimal group with one tool:

kind: Plugin
name: CRM Integration
description: Tools for posting leads to the corporate CRM
dependencies:
  - submodules/crm_logic.py
  - requirements.txt
tools:
  - kind: Tool
    object_name: PostLeadToCRM
    name: post_lead
    description: Sends client contact details to the corporate CRM system.
    implementation: crm_logic.post_lead
    parameters:
      - name: client_name
        type: string
        description: Name of the client
      - name: client_email
        type: string
        description: Email of the client

The portal reads only name, description, and dependencies from the file, plus the entries under tools and skills, which it shows in the Tools column of the tool group. The rest of the format is interpreted when an agent runs.

Declare a tool

Each entry under tools describes one tool the agent can call. A tool runs only when the model decides to call it while composing a reply.

Key	Required	Value
kind	Yes	Must be Tool.
object_name	Yes	The tool's internal identifier. This is the name you list under available_tools in a workflow state — see Where the values surface.
name	Yes	The name the model sees and uses to call the tool. This is what the Tools column shows for the tool.
description	Yes	What the tool does. The model reads this to decide when to call the tool, so write it for the model.
implementation	Yes	The Python callable that runs when the tool is called. See Dependencies and implementation bindings.
parameters	Yes	The arguments the tool takes. A list of parameter objects, or [] for a tool that takes no arguments. See Parameter schema.

A tool that takes no arguments uses an empty list:

- kind: Tool
  object_name: TransferToTheOperator
  name: transfer_to_operator
  description: Transfers the conversation to the operator
  parameters: []
  implementation: transfer_to_operator.transfer_to_operator

Parameter schema

Each entry under a tool's parameters describes one argument the model fills in when it calls the tool.

Key	Required	Value
name	Yes	The parameter name the model uses.
type	Yes	The value type. See Parameter types.
description	Yes	What the value is. The model reads this to fill the parameter.
optional	No	Set true to make the parameter optional. Defaults to false, meaning required.

parameters:
  - name: user_name
    description: User's name from HumanFullName field.
    type: str
  - name: user_email
    description: User's email from HumanEmail field. If it is --EMPTY--, then fill as None.
    type: str | None

Parameter types

The type key takes a type expression that is translated to the model's tool-calling schema.

Type expression	Meaning
string (or str)	Text.
integer (or int)	A whole number.
number (or float)	A number.
boolean (or bool)	A true/false value.
array (or list)	A list of values.
object (or dict)	A structured value.
null (or None)	A null value.
datetime.date	A calendar date.
datetime.datetime	A date with a time.
Literal[value1, value2, ...]	One value from a fixed set.
list[<type>]	A typed list, for example list[str].
dict[<key_type>, <type>]	A typed object, for example dict[str, int].
Optional[<type>]	The type or null, equivalent to <type> | None.
<type1> | <type2>	Any of the listed types, for example str | None.

The forms nest, so list[str | int] | None and list[list[str]] are both valid.

Declare a skill

Each entry under skills describes a skill — a function that runs automatically at a fixed point in a conversation, instead of being called by the model while it composes a reply.

Key	Required	Value
kind	Yes	Must be Skill.
name	Yes	The skill name. This is what the Tools column shows for the skill.
description	Yes	What the skill does.
implementation	Yes	The Python callable that runs. See Dependencies and implementation bindings.
session_init_call	No	Set true to run the skill when a session starts. Defaults to false.
session_finish_call	No	Set true to run the skill when a session finishes. Defaults to false.
inputs	No	A list of values the skill takes. Each entry has name, description, and dtype (the value type).

A skill that runs at the start of every session:

skills:
  - kind: Skill
    name: SessionInit
    description: Handle with sensitive data
    session_init_call: true
    implementation: collector_campaign_init.session_init

A skill runs automatically at the point its trigger key sets: session_init_call: true runs it when a session starts, and session_finish_call: true runs it when a session finishes. A skill with neither trigger set does not run on its own.

note

Skills and tools serve different purposes. A tool is called by the model when it decides to use it. A skill runs automatically at the session point you configure, with no model decision. Use a tool for an action the agent takes in the course of a conversation, and a skill for setup or cleanup that should always happen.

Dependencies and implementation bindings

The implementation key binds a tool or skill to the Python callable that runs it. Write it as module.callable — the module is the Python file (without the .py extension) listed under dependencies, and the callable is the function inside it.

implementation: crm_logic.post_lead

This calls the post_lead function in the crm_logic.py file.

The dependencies list names the files the group needs, as paths relative to the shared file storage shown on the Resources tab of the Tools screen:

dependencies:
  - submodules/crm_logic.py
  - requirements.txt

• List every code file an implementation refers to. Each path is matched against a file in the shared storage; if a listed file has not been uploaded, the group's status is Incomplete until you upload it.
• Include a requirements.txt when your code uses third-party Python packages. The packages it lists are installed for the group.

Built-in tools

Some tool names are built into Flametree and do not come from a definition file. You list them under available_tools the same way as your own tools, by their object_name:

object_name	What it does
FinishSession	Ends the conversation session.
TriggerKBSearch	Searches the knowledge sources connected to the agent.
ReportUnansweredQuestion	Records an on-topic question the agent could not answer, so you can review it later.
SendChatMessage	Sends a chat message to the customer. Required only in legacy workflows that use the available_tools: SingleStatefulOutboundAgent: format.

You do not declare these in a definition file — they are always available to reference in a workflow.

Where the values surface

The values in the definition file appear in several places in the portal:

• Tools screen. The Tools column of a tool group lists each tool's name and each skill's name, taken from the definition file. The group's name and description become the group's name and description. See Tools.
• available_tools in a workflow. To let an agent call a tool, add the tool's object_name under available_tools in the workflow state where the agent may use it. The name is case-sensitive and must match the object_name exactly. See Advanced mode. Skills do not go in available_tools — they run automatically from their trigger keys.
• Playground and Logs. When you test in the Playground, a tool or skill call appears in the test session's logs: System Logs record the call and its result, and Trace Logs show how the model chose to call a tool. See Sessions.

Related pages

• Tools — create a tool group, upload files, attach it to an agent, and test it
• YAML basics — the YAML syntax these files use
• Advanced mode — list a tool's object_name under available_tools in a workflow state
• Playground — test an agent's tools without connecting a channel
• Sessions — read system and trace logs for tool and skill calls